App Extensions: Guide

This guide describes how to get started developing App Extensions. It contains the following:

• An App Extensions-flavored variation on setting up a draft app
• Example requests and responses for the App Extensions mutations and query
• Implementation and code examples

Prerequisites

Before getting started working with App Extensions, make sure you have the following:

• A BigCommerce store; we recommend using a sandbox store or other non-production store.
• A Developer Portal account registered to the same email account that owns the sandbox store.
• General familiarity with developing BigCommerce apps. To familiarize yourself, see the Apps Guide or Apps Quick Start.

OAuth scopes

The following section describes the process for creating an app profile and app-level API account. Configure the following OAuth scopes as directed in Setup:

Setup

$
git clone git@github.com:bigcommerce/sample-app-nodejs.git app-with-extensions
$
$
cd app-with-extensions
$
$
npm install
$
$
npm run dev
$
$
# open new terminal window
$
$
npm install ngrok
$
$
ngrok http 3000

$
#Get the Client ID and Secret from the Developer Portal
$
# /developer/docs/integrations/apps/quick-start#register-a-draft-app
$
CLIENT_ID={app client id}
$
CLIENT_SECRET={app secret}
$
$
# Test locally with ngrok
$
# /developer/docs/apps/guide/development#testing-locally-with-ngrok
$
AUTH_CALLBACK=https://{ngrok_url}/api/auth
$
$
# Replace jwt key with a 32+ random character secret
$
JWT_KEY={SECRET}
$
$
# Specify the type of database
$
DB_TYPE=firebase
$
$
# If using firebase, enter your config here
$
FIRE_API_KEY={firebase key}
$
FIRE_DOMAIN={firebase domain}
$
FIRE_PROJECT_ID={firebase project id}
$
$
# If using mysql, enter your config here
$
MYSQL_HOST={mysql host}
$
MYSQL_DATABASE={mysql database name}
$
MYSQL_USERNAME={mysql username}
$
MYSQL_PASSWORD={mysql password}
$
MYSQL_PORT={mysql port *optional*}
$
$
# BigCommerce API URL
$
API_URL=api.bigcommerce.com

$
npm run db:setup
$
$
npm run dev

Example requests

This section contains examples of App Extensions-related GraphQL Admin API queries and mutations. It presents mutations and their variables separately. You can use a tool like Postman or Altair to make requests; if you prefer to get started quickly in Postman, see the App Extensions Postman collection.

Use the following HTTP configuration to send requests:

POST https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json

The following examples direct you to stringify the GraphQL query portion of your requests, but how this works in practice varies depending on the client you use.

Create an App Extension

The createAppExtension mutation registers an App Extension that opens a side panel on the store control panel’s customers page to let users read and write notes about interactions with specific customers.

1
mutation AppExtension($input: CreateAppExtensionInput!) {
2
  appExtension {
3
    createAppExtension(input: $input) {
4
      appExtension {
5
        id
6
        context
7
        model
8
        url
9
        label {
10
          defaultValue
11
          locales {
12
            value
13
            localeCode
14
          }
15
        }
16
      }
17
    }
18
  }
19
}

Get a store’s App Extensions

The Store appExtensions query returns a list of the store’s App Extensions registered to the API account that makes the request, along with any details requested using the query schema. Note that all GraphQL requests use the POST method.

1
query {
2
  store {
3
    appExtensions {
4
      edges {
5
        node {
6
          id
7
          url
8
          model
9
        }
10
      }
11
    }
12
  }
13
}

Update an App Extension

The updateAppExtension mutation can update the label object and the url of an existing App Extension. All other properties are non-mutable.

Changes to the label object overwrite existing values, rather than upserting. Be sure to send the full label object you intend the App Extension to have.

Note that the UpdateAppExtensionInput has two properties, id and data. Add the desired new values for the url or label properties to the data attribute.

1
mutation AppExtension($input: UpdateAppExtensionInput!) {
2
  appExtension {
3
    updateAppExtension(input: $input) {
4
      appExtension {
5
        id
6
        url
7
        label {
8
          defaultValue
9
        }
10
      }
11
    }
12
  }
13
}

Delete an App Extension

The deleteAppExtension mutation deletes an App Extension. It cannot be recovered. Note that you can request an additional property that isn’t accessible to the other queries and mutations, deletedAppExtensionId. You can’t request any other properties in the delete mutation.

1
mutation AppExtension($input: DeleteAppExtensionInput!) {
2
  appExtension {
3
    deleteAppExtension(input: $input) {
4
        deletedAppExtensionId
5
    }
6
  }
7
}

Example code

Starter app

The BigCommerce Next.js starter app (GitHub) contains a branch that features a working, end-to-end App Extensions reference implementation.

Code sample

The following Node.js code sample uses the node-fetch http request package to create a color picker App Extension that opens in a side panel on the View Products page of the merchant’s store control panel.

import setAppExtension from "./set-app-extension";
// Hardcoded example of store-specific credentials
const subjectStore = {
  store_hash: "qwerty",
  // the store's access_token from your DB
  access_token: "xxxxxalphanumxxxxx"
};
// stringified GraphQL Mutation
const registerAppExtensionMutation = `
mutation AppExtension($input: CreateAppExtensionInput!) {
  appExtension {
    createAppExtension(input: $input) {
      appExtension {
        id
        context
        model
        url
        label {
          defaultValue
          locales {
            value
            localeCode
          }
        }
      }
    }
  }
}
`;
// This GraphQL variable describes the particular App Extension your app is registering; modify for your use case
const colorPickerExtension = {
  input: {
    context: "PANEL",
    model: "PRODUCTS",
    url: "/product/${id}/pigment",
    label: {
      defaultValue: "Select Color",
      locales: [
        {
          value: "Pick Color",
          localeCode: "en-US"
        },
        {
          value: "Choisissez la couleur",
          localeCode: "fr-FR"
        },
      ],
    },
  },
};
return setAppExtension(
  subjectStore,
  registerAppExtensionMutation,
  colorPickerExtension
);

Resources

Related articles

• Developer Portal
• Single-Click App OAuth Flow

External resources

• node-fetch http request package (npmjs.com)