Bigcommerce Sample App: Ruby

This is a small Sinatra application that implements the OAuth callback flow for Bigcommerce Single Click Apps and uses the Bigcommerce API to pull a list of products on a Bigcommerce store. For information on how to develop apps for Bigcommerce stores, see our Developer Portal.

We hope this sample app gives you a good starting point for building your next killer app! What follows are steps specific to running and installing this sample appication.

Registering the app with Bigcommerce

• Create a trial store on Bigcommerce
• Go to the Developer Portal and log in.
• Go to "My Apps"
• Click the button "Create an app", enter a name for the new app, and then click "Create"
• You don't have to fill out all the details for your app right away, but you do need to provide some core details in section 4 (Technical). Note that if you are just getting started, you can use localhost for your hostname, but ultimately you'll need to host your app on the public Internet.
  • Auth Callback URL: https://<app hostname>/auth/bigcommerce/callback
  • Load Callback URL: https://<app hostname>/load
  • Uninstall Callback URL: https://<app hostname>/uninstall
• Enable the Products - Modify scope under OAuth scopes. This sample app uses that scope, but if you need others, you'll need to specify them here and then modify the scopes method in hello.rb to match.
• Click Save & Close on the top right of the dialog.
• You'll now see your app in a list in the My Apps section of Develper Portal. Hover over it and click View Client ID. You'll need these values in the next step.

Getting started

• Clone this repo: git clone git@github.com:bigcommerce/hello-world-app-ruby-sinatra.git
• Change to the repo directory: cd hello-world-app-ruby-sinatra
• Install gems: bundle install --path vendor/bundle
• Copy .env-example to .env
• Edit .env:
  • Set BC_CLIENT_ID and BC_CLIENT_SECRET to the values obtained from Developer Portal.
  • Set APP_URL to https://<app hostname>
  • Set SESSION_SECRET to a long random string, such as that generated by ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
• Run the app: foreman start

Hosting the app

In order to install this app in a Bigcommerce store, it must be hosted on the public Internet. You can get started in development by simply running foreman start to run it locally, and then use localhost in your URLs, but ultimately you will need to host it somewhere to use the app anywhere other than your development system. One easy option is to put it on Heroku.

Heroku

Note: It is assumed that you already have a Heroku account, have the Heroku toolbelt installed, and have authenticated with the toolbelt. See Heroku for details.

• Create a new Heroku app: heroku create <appname>
• Push the project to Heroku: git push heroku master -u
• Set APP_URL in .env to https://<appname>.herokuapp.com
• Add the heroku-config plugin: heroku plugins:install git://github.com/ddollar/heroku-config.git
• Push the local environment variables to heroku: heroku config:push

In the Bigcommerce Developer Portal, you'll need to update the app's callback URLs:

• Auth Callback URL: https://<appname>.herokuapp.com/auth/bigcommerce/callback
• Load Callback URL: https://<appname>.herokuapp.com/load
• Uninstall Callback URL: https://<appname>.herokuapp.com/uninstall

Installing the app in your trial store

• Login to your trial store
• Go to the Marketplace and click My Drafts. Find the app you just created and click it.
• A details dialog will open. Click Install and the draft app will be installed in your store.