(Heroku instructions)

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 BigcCommerce 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 application.

Registering the app with BigCommerce

• Create a trial store on BigCommerce
• Go to the Developer Portal and click "My Apps".
• Login to your account.
• 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.
  • Note: If you are managing customer information through the API (such as with the Recently Purchased Products Block example below) then you will need to also enable the Customers scope to at least read.
• 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 [email protected]: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
• Ensure you have redis-server running (if not brew install redis on OSX will do it)
• 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)"
  • REDIS_URL should be automatically set to the default developer creds, but if you changed your redis server credentials you'll have to set them here too.
• 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.

Getting started (Heroku version)

1. Click this button:
2. Fill in the details from the app portal on the Heroku deployment page

• See Registering the app with BigCommerce above. Ignore the callback URLs, just save the app to get the Client ID and Client Secret.

3. Deploy the app, and click "view" when it's done
4. Take the callback URLs from the instructions page and plug them into the dev portal. All done!

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.

Showing the Recently Purchased Products Block with JWT

This example repo contains the ability to securely show recently purchased products. This is how it looks:

Adding the block to your theme

1. Edit your Footer.html file in blueprint or Footer Scripts if you're using Stencil and add:

   <script>
   var appClientId = "**BC_CLIENT_ID**"; // TODO: Fill this in with your app's client ID.
   var storeHash = "**TEST_STORE_HASH**"; // TODO: Fill this in wit the test store's store hash (found in base url before the `store-` part)
   var appUrl = "**APP_URL**"; // TODO: Replace this with your app's URL.
   
   // Get the JWT token from the BC server signed first.
   $.get('/customer/current.jwt?app_client_id='+appClientId, function(jwtToken) {
     // Now that we have the JWT token, use it to get the recent purchases block.
     $.get(appUrl+'/storefront/'+storeHash+'/customers/'+jwtToken+'/recently_purchased.html', function(htmlContent) {
       $('#recent_purchases_block').html(htmlContent, true);
     });
   });
   </script>​

2. Put <div id="recent_purchases_block"></div> wherever you want the block to appear. If you're using blueprint it is recommended that you put it in default.html right before %%Panel.SideTopSellers%%.
3. Log in as a customer in your store's frontend (or create a customer account if one doesn't exist yet), place an order then go to the section where you added the <div id="recent_purchases_block"></div>. You should see the Recently Purchased Products block appear.