Guides

Supported Scopes, Events & Utils Functions

Suggest Edits

Recap of the supported scope

SDK provides functions to allow developers to get storefront info easily, below provide a quick overview on the supported scope

a. Get current page, theme, loaded language, loaded currency

b. Get merchant ID, cookie consent

c. Get products (id, categoryIds, tags) | @ PLP & PDP page only

d. Get metafields value

e. Get order id | @ Order Confirm & Order Detail only

f. Get info of products | @ Order Confirm, Order Detail & Promotion Page only

g. Get shopping cart info | @ Cart & Checkout Page

Events

Following is a list of supported event topics for the SDK to listen to. For more information about event listeners, refer to here.

  • currency.changed
  • cart.update

Utils Functions

All functions listed here are async functions. Here are the list of supported utils functions:

  • getCurrentPageIdentifier()
  • getThemeKey()
  • getLoadedLanguage()
  • getLoadedCurrency()
  • getMerchantId()
  • getCookieConsent()
  • getPDPProduct()
  • getPLPProducts()
  • getMetafieldValues({ resource_type, resource_ids, keys })
  • getOCPOrder()
  • getOCPProducts()
  • getODPOrder()
  • getODPProducts()
  • getPPProducts()
  • getCPCartItems()
  • getCOPCartItems()

Event Payload Reference Example

currency.changed

Return Value:

A string that represents the currency code.

Example Payload of the Event

sdk.events.addEventListener('currency.changed', (payload) => {
  console.log(payload);
  // Output: hkd
});

cart.update

Return Value:

An object including the latest information of the cart.

Example Payload of the Event

sdk.events.addEventListener('cart.update', (payload) => {
    console.log(payload);
    // Output: {
    //     "id": "1317718",
    //     "owner_id": "664c73b22ffa7a00437addce",
    //     "owner_type": "User",
    //     "merchant_id": "6270db2f9ece2a1f1089d7ac",
    //     "items": [
    //         {
    //             "_id": "2033165",
    //             "product_id": "64f695ad931347370a5a96a4",
    //             "variation_id": "",
    //             "quantity": 1,
    //             ...
    //         },
    //         {
    //             "_id": "2033214",
    //             "product_id": "66589fb1e9bd62001fe9953b",
    //             "variation_id": "62d517722c015a00312c7df4",
    //             "quantity": 1,
    //             ...
    //         }
    //     ],
    //     ...
    // }
});

Utils Functions Reference Example

getCurrentPageIdentifier()

Get the current page identifier.

Available Pages: all

Return Value:

A string that represents the current page identifier.

Example

pageIdentifier = await sdk.utils.getCurrentPageIdentifier();

console.log(pageIdentifier);
// Output: home

getThemeKey()

Get merchant current theme key.

Available Pages: all

Return Value:

A string that represents the merchant current theme key.

Example

themeKey = await sdk.utils.getThemeKey();

console.log(themeKey);
// Output: ultra_chic

getLoadedLanguage()

Get current loaded language.

Available Pages: all

Return Value:

An object that represents the loaded language:

  • name: the name of the language (e.g. 繁體中文)
  • code: the code of the language (e.g. zh-hant)
loadedLanguage = await sdk.utils.getLoadedLanguage();

console.log(loadedLanguage);
// Output: {
//   "name": "繁體中文",
//   "code": "zh-hant"
// }

getMerchantId()

Get merchant ID.

Available Pages: all

Return Value:

A string that represents the merchant ID.

merchantId = await sdk.utils.getMerchantId();

console.log(merchantId);
// Output: 62958ab9a0883410b6a1c18f

getCookieConsent()

Get the current cookie consent.

Available Pages: all

Return Value:

An object that represents the cookie consents:

  • necessary: a boolean that represents if the user has agreed to necessary cookies.
  • statistical: a boolean that represents if the user has agreed to statistical cookies.
  • marketing: a boolean that represents if the user has agreed to marketing cookies.
  • functionality: a boolean that represents if the user has agreed to functionality cookies.

Example:

cookieConsents = await sdk.utils.getCookieConsent();

console.log(cookieConsents);
// Output: {
//    "necessary": true,
//    "statistical": true,
//    "marketing": true,
//    "functionality": true
//}

getLoadedCurrency()

Get the loaded currency.

Available Pages: all

Return Value:

A string that represents the loaded currency.

Example:

loadedCurrency = await sdk.utils.getLoadedCurrency();

console.log(loadedCurrency);
// Output: hkd

getPDPProduct()

Get product in Product Detail Page

Available page: Product Detail Page (product_detail)

Return Value:

An object that contains info of the product in the PDP:

  • id: A string that represents the product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product

Example:

product = await sdk.utils.getPDPProduct();

console.log(product);
// Output: {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31"
//     ]
// }

getPLPProducts()

Get products in Product Listing Page

Available page: Product Listing Page (product_list)

Return Value:

An array of objects that contains info of the products in the PLP:

  • id: A string that represents the product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product

Example:

products = await sdk.utils.getPLPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31",
//         "6295b6664586dd003c1d89d8"
//     ],
//   }
// ]

getMetafieldValues({ resource_type, resource_ids, keys })

Get metafield values of supported resources

Available Page: all

Parameters:

  • resource_type: the supported resource type of metafields (e.g. product, customer, ...)
    • For customer, order, order_item types, you can only get the metafield values only when the user has logged in.
  • resource_ids: an array of string that represents the resource IDs of the metafield. For different resource type, you can input different length of resource IDs.
    • merchant, customer: You don't need to input this field
    • product: You can input multiple product IDs as the resource_ids. Max length is 72.
    • order, order_item: You can only input 1 order ID as the resource_ids
    • cart_item: You can input multiple identifiers as the resource_ids. Max length is 72.
      • For cart_item, the identifier is in the format of {cart_id}-{product_id}-{variation_id}
      • If the product does not contain a variation, the format would be {cart_id}-{product_id}
  • keys: an array of string that represents the metafields' keys

Return Value:

An object that contains the metafield values for each resource ID:

  • key: {resource_id}
  • value: An array of objects of metafields
    • namespace: namespace (i.e. app ID) of the metafield
    • key: key of the metafield
    • field_type: field_type of the metafield
    • field_value: field_value of the metafield

Example:

metafieldValues = await sdk.utils.getMetafieldValues(
  { resource_type: 'merchant', keys: ['example_key_1'] }
);

console.log(metafieldValues);
// Output: {
//   '63bbbe56c1369e0039e5aa3c': [		// resource ID
//     {
//       namespace: "62958abc38aec9003b96d538",		// app ID
//       key: "example_key_1",
//       field_type: "number_integer",
//       field_value: 100,
//     }
//   ]
// }

getOCPOrder()

Get order in Order Confirm Page

Available page: Order Confirm Page (order_confirm)

Return Value:

An object that contains info of the order in the OCP:

  • id: A string that represents the order ID

Example:

order = await sdk.utils.getOCPOrder();

console.log(order);
// Output: {
//   "id": "63bbbe56c1369e0039e5aa3c"
// }

getOCPProducts()

Get info of products in the order in Order Confirm Page

Available page: Order Confirm Page (order_confirm)

Return Value:

An array of objects that contains info of the products in that order in OCP:

  • id: A string that represents the product ID

Example:

products = await sdk.utils.getOCPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c"
//   }
// ]

getODPOrder()

Get order in Order Detail Page

Available page: Order Detail Page (order_detail)

Return Value:

An object that contains info of the order in the ODP:

  • id: A string that represents the order ID

Example:

order = await sdk.utils.getODPOrder();

console.log(order);
// Output: {
//   "id": "63bbbe56c1369e0039e5aa3c"
// }

getODPProducts()

Get info of products in the order in Order Detail Page

Available page: Order Detail Page (order_detail)

Return Value:

An array of objects that contains info of the products in that order in ODP:

  • id: A string that represents the product ID

Example:

products = await sdk.utils.getODPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c"
//   }
// ]

getPPProducts()

Get info of products of the promotion in Promotion Page

Available page: Promotion Page (promotion_page)

Return Value:

An array of objects that contains info of the products in the PP:

  • id: A string that represents the product ID
  • tags: A string that represents the tags of products, separated with ,
  • category_ids: An array of string that represents the IDs of categories of the product

Example:

products = await sdk.utils.getPPProducts();

console.log(products);
// Output: [
//   {
//     "id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31",
//         "6295b6664586dd003c1d89d8"
//     ],
//   }
// ]

getCPCartItems()

Get cart id and info of products in Cart Page

Available page: Cart Page (cart)

Return Value:

An object that contains info of the cart items in the CP:

  • id: A string that represents the order ID
  • items: An array of objects that contains info of products in the cart for you to form the cart_item identifier

Example:

cartItems = await sdk.utils.getCPCartItems();

console.log(cartItems);
// Output: {
//   "id": "1309639",
//   "items": [
//     {
//       "product_id": "64f695ad931347370a5a96a4",
//       "variation_id": ""
//     },
//     {
//       "product_id": "64f695f99313475e7f5a9160",
//       "variation_id": "62d517722c015a00312c7df4"
//     }
//   ]
// }

getCOPCartItems()

Get cart id and info of products in Checkout Page

Available page: Checkout Page (checkout)

Return Value:

An object that contains info of the cart items in the COP:

  • id: A string that represents the order ID
  • items: An array of objects that contains info of products in the cart for you to form the cart_item identifier

Example:

cartItems = await sdk.utils.getCOPCartItems();

console.log(cartItems);
// Output: {
//   "id": "1309639",
//   "items": [
//     {
//       "product_id": "64f695ad931347370a5a96a4",
//       "variation_id": ""
//     },
//     {
//       "product_id": "64f695f99313475e7f5a9160",
//       "variation_id": "62d517722c015a00312c7df4"
//     }
//   ]
// }

Updated 5 months ago