Creating an External Installation Button

Single-click apps can be installed from outside the BigCommerce control panel. For example, an install button on your company's site that directs the merchant to download your app. This tutorial provides step-by-step instructions for creating an external install button for BigCommerce single-click apps.

Creating an install button

First, embed an install button like the one below, at any web location from which you’d like to enable app installation.

Install Button

Redirect anyone who presses your button to: https://login.bigcommerce.com/app/{CLIENT_ID}/install.

Configuring the button

When clicked, your button should open a modal similar to the image below. We recommend a modal sized 900px wide by 450px high.

Install Button

Your button will link merchants to BigCommerce's install endpoint for your application. Once the merchant clicks the link, they will be prompted to sign in and authorize your application.

Rendering success and failure pages

Modify your web site's server-side code to serve either a success or failure page, depending on whether the external installation was successful or unsuccessful.

If you skip this step, your application will load in the iFrame created by your button. To ensure a good experience for your users, we strongly recommend that you return a confirmation page, instead of allowing your application to be loaded in that modal.

Handling errors

If your application's installation was initiated and completed through an external link, BigCommerce will send your auth callback endpoint an extra parameter called external_install.

If you receive this parameter and there are no errors, make a GET request to the install succeeded endpoint.

GET /app/{CLIENT_ID}/install/succeeded  HTTP/1.1
Host: login.bigcommerce.com

If there were errors, make a GET request to the install failed endpoint:

GET /app/{CLIENT_ID}/install/failed  HTTP/1.1
Host: login.bigcommerce.com

Depending on which endpoint you call, BigCommerce will render a success or failure page to the modal.

Code samples

Handling errors in Lua:

Example: Lua error handling

if params['external_install']
    return get 'https://login.bigcommerce.com/app/m8e1mkkmjw2xjinydqz7ie05to1y2nk/install/succeeded'
end
 
redirect '/'
 
rescue => e
if params['external_install']
    return get 'https://login.bigcommerce.com/app/m8e1mkkmjw2xjinydqz7ie05to1y2nk/install/failed'
end

Creating an External Installation Button

Creating an install button

Configuring the button

Rendering success and failure pages

Handling errors

Code samples

Next steps

Resources

Sample apps

Tools

Blog posts