App Development Best Practices

Review the following best practices before submitting your app to the App Marketplace.

OAuth flow

Follow security best practices and requirements

RFC 6749 discusses OAuth security considerations, recommendations, and requirements. Here’s a summary of important items applicable to apps:

• Request access tokens with minimal scopes necessary.
• Serve all redirect URIs over TLS.
• Keep access tokens confidential in transit and storage.
• Do not transmit access tokens, refresh tokens, or client credentials in the clear.
• Do not transmit authorization codes in the clear.
• Educate end-users about the risks phishing attacks pose.
• Provide mechanisms that make it easy for end-users to confirm the authenticity of your app.
• Implement CSRF protection on redirect URI.

For details, see Security Considerations in RC6749. For a list of the top web application security risks and best practices to avoid them, see OWASP Top Ten.

API requests

For recommendations on API request-related best practices, including rate limits, threading, parallel requests, and the finer points of request headers, see our article on Best Practices.

Webhook events

Use webhooks to keep app data up-to-date

Rather than polling endpoints, get notified when updates occur by subscribing to webhooks.

User interface

Manage user session timeouts

The BigCommerce SDK keeps apps synchronized with the control panel. To use it, load the SDK at the top of your application’s main index. Since it runs as frontend code, it must be executed in the browser to function properly.

Run the following command to import the library:

import 'bigcommerce-app-sdk-js';

Next, initialize the SDK. This should be done in the first part of the application that has access to the window object. In React-based applications, including Next.js, this can be done inside of useEffect or componentDidMount (for class components).

window.bcAsyncInit = function() {
  Bigcommerce.init({
    onLogout: callback
  });
}

To enhance security, you can pass an onLogout callback, which triggers when a user logs out of the control panel—even from a separate tab. For example, the Next.js sample app calls an internal API to remove the user from the active session. See the following example for more details.

Streamline new user onboarding

• If your app has a new user form, we recommend auto-filling input fields with data from the Store Information API, which manages much of the info you need.
• If your app doesn’t have an approval process for new users, consider automatically generating accounts for new stores that install your app.
• If your app requires the user to sign in at launch, use the information BigCommerce sends to your callback URL to authenticate the user without asking for a username and password each time.
• If you plan to share user testimonials, add a link to your full case study in the case studies field.

Offer multi-user access

Merchants often have more than one person who can access a store’s control panel. BigCommerce allows additional users to access an app when the store owner has granted them appropriate permissions. The requirements for supporting multi-user app access are:

• The app must save the API account access token for each store with its store_hash, rather than a user’s info.
• In the app’s Developer Portal profile, you must enable multiple users.

In the payload returned when a user launches an app, users are distinguished by owner_email versus user_email. If these two emails match, the user is the store owner.

Enabling user removal is optional. If you want merchants to be able to remove users, you can do so by writing a remove_user callback and adding its URL to your app’s Developer Portal profile. For more advanced implementations, you can enable the store owner to grant specific permissions to different non-admin users. For example, person1@example.com could be permitted to edit product inventory but not view orders. If you decide to implement user permissions in your app, it’s a great feature to advertise.

For more information, see Multi-User Support.

Deployment

Consider hosting on Google Cloud Platform’s us-central1 region

BigCommerce hosts Google Cloud Platform in the us-central1 region; maximize performance by hosting in the same region.

Next steps

• Check requirements.
• Publish your app.

Resources

Sample apps

• Node / React / Next.js
• Python / Flask
• PHP / Silex
• Ruby / Sinatra
• Laravel / React

Tools

• Node API Client
• Python API Client
• PHP API Client
• Ruby API Client
• Ruby OmniAuth Gem
• BigDesign Developer Playground
• Figma Component Library

Blog posts

• How to Test App Authentication Locally with ngrok
• Building a BigCommerce App Using Laravel and React
• BigDesign Tutorial