Features
The Features
action set allows you to find out what features are available in the current app context, and to request currently unavailable features.
Setup
Create an app and import the Features
module from @shopify/app-bridge/actions
. Note that we'll be referring to this sample application throughout the examples below.
import createApp from '@shopify/app-bridge';
import {Features, Group, Scanner} from '@shopify/app-bridge/actions';
const app = createApp({
apiKey: '12345',
shopOrigin: shopOrigin,
});
Subscribe to feature availability updates
app.subscribe(Features.Action.UPDATE, function () {
// This callback is a reminder that a feature's availability has
// changed.
// Call `app.featuresAvailable()` to get all available features
});
App.featuresAvailable()
Calling app.featuresAvailable()
returns a promise that evaluates to the entire set of available features for the app. The feature set is represented as an object containing groups, the actions within each group, and the permissions for each action (Dispatch
and Subscribe
).
If Dispatch
is equal to true
, then you will be able to send that type of action within your app. Likewise if Subscribe
is equal to true
, then you will be able to subscribe to dispatches of that type of action.
If a group is not present in the state then it can be assumed that all actions contained in that group are also not available.
app.featuresAvailable().then(function (state) {
/* All actions will be in the state object:
{
Cart: {...},
Button: {...},
Modal: {...},
...
Scanner: {...},
Share: {...}
} */
});
If you want to limit your resulting state to a subset of groups, then pass in a group parameter.
app.featuresAvailable(Group.Cart).then(function (state) {
// state will contain only Cart actions
/*
{
Cart: {
FETCH: {
Dispatch: false,
Subscribe: false
},
REMOVE_LINE_ITEM_PROPERTIES: {
Dispatch: false,
Subscribe: false
}
...
}
} */
});
Multiple group filters are also supported by using ...rest
parameters.
app.featuresAvailable(Group.Cart, Group.Button, Group.Modal).then(function (state) {
// state will contain only Cart, Button, and Modal actions
/*
{
Cart: {...},
Button: {...},
Modal: {...}
} */
});
Cart
If you experience feature availability errors while trying to access Cart actions on Point of Sale, try wrapping that code in a subscription to Features.Action.UPDATE
.
// Subscribe to the features update action as early as possible
const unsubscribe = app.subscribe(Features.Action.UPDATE, function () {
app.featuresAvailable(Group.Cart).then((features) => {
const hasFetchCart = features.Cart[Cart.Action.FETCH];
if (hasFetchCart) {
unsubscribe();
// Do something
}
});
});
Features Update action
Group | Features |
---|---|
Action | UPDATE |
Action Type | APP::FEATURES::UPDATE |
Description | Dispatches when a feature's available state changes. |
Response
Key | Type | Description |
---|---|---|
Main |
Object | The availability state of the features in the main context. |
Modal |
Object | The availability state of the features in the modal context. |
Features Request action
Group | Features |
---|---|
Action | REQUEST |
Action Type | APP::FEATURES::REQUEST |
Description | Requests for a feature to be enabled. May result in an authorization dialog to appear, depending on the platform it is dispatched on. |
If an action is not available when you call app.featuresAvailable()
, then you can use the APP::FEATURES::REQUEST
action to request either a group of actions or a single action inside a group to be enabled. This is particularly useful when the app is running on a mobile device and requesting a hardware feature, such as the scanner, that needs authorization from the user.
The workflow for enabling a feature includes two parts: subscribing to APP::FEATURES::REQUEST::UPDATE
and dispatching APP::FEATURES::REQUEST
. APP::FEATURES::REQUEST
is the input and APP::FEATURES::REQUEST::UPDATE
is the output.
Requesting Camera Scanner actions:
var features = Features.create(app);
features.subscribe(Features.Action.REQUEST_UPDATE, function (payload) {
if (payload.feature[Scanner.Action.OPEN_CAMERA]) {
var Dispatch = payload.feature[Scanner.Action.OPEN_CAMERA].Dispatch;
console.log("Camera Scanner has been ".concat(Dispatch ? "enabled" : "disabled"));
}
});
features.dispatch(Features.Action.REQUEST, {
feature: Group.Scanner,
action: Scanner.Action.OPEN_CAMERA
});
Request
Key | Type | Description |
---|---|---|
feature |
String | The feature group that you would like to enable. |
action |
String? | An optional action within the group to enable. All actions within the group will be enabled if an action is not specified. |
Features Request Update action
Group | Features |
---|---|
Action | UPDATE |
Action Type | APP::FEATURES::UPDATE |
Description | Dispatches with the result of a features request action. |
Response
Key | Type | Description |
---|---|---|
feature |
Object | The new state of the requested feature. |
Application context
Shopify App Bridge applications can be opened in different places. We refer to each of these places as a context. Each context makes a set of features available to the application. Different contexts can provide different feature sets.
For instance, the Modal context has a different set of features available than the Main context.
To check which context an application is in, you can use app.getState()
. Read more about app.getState
.
app.getState('context').then(function (context) {
console.log('Context is: ', context); // Context is: Main
});