Guides

List of Available Utils Functions & Events

Supported scopes

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
  • page.variationChanged | @ PDP page only
  • page.quantityChanged | @ PDP page only
  • page.addonQuantityChanged | @ PDP page only

Utils Functions

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

  • getCurrentPageIdentifier()
  • getCurrentThemeKey()
  • 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.

Supported Pages:

PLP / PDP / Order Confirm page / Order Detail page / Cart page / Checkout Page

Example Payload of the Event

sdk.events.addEventListener('cart.update', (payload) => {
    console.log(payload);
    // Output: {
    //     "id_v2": "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,
    //             ...
    //         }
    //     ],
    //     ...
    // }
});

page.variationChanged

Triggered when the selected variation changes in PDP.

Return Value:

An object:

  • productId: A string of the main product ID.
  • variationId: A string of the selected variation ID.

Example Payload of the Event

sdk.events.addEventListener('page.variationChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "63bbbe56c1369e0039e5aa3c",
  //   "variationId": "62d517722c015a00312c7df4"
  // }
});

page.quantityChanged

Triggered when the main product quantity changes in PDP.

Return Value:

An object:

  • productId: A string of the main product ID.
  • variationId: A string of the selected variation ID (null if none selected).
  • quantity: A number of the current quantity.

Example Payload of the Event

sdk.events.addEventListener('page.quantityChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "63bbbe56c1369e0039e5aa3c",
  //   "variationId": null,
  //   "quantity": 2
  // }
});

page.addonQuantityChanged

Triggered when an add-on product quantity changes in PDP.

Return Value:

An object:

  • productId: A string of the add-on product ID.
  • variationId: A string of the add-on variation ID (null if none).
  • mainProductId: A string of the main product ID.
  • mainVariationId: A string of the main product's selected variation ID (null if none).
  • quantity: A number of the current add-on quantity.

Example Payload of the Event

sdk.events.addEventListener('page.addonQuantityChanged', (payload) => {
  console.log(payload);
  // Output: {
  //   "productId": "66589fb1e9bd62001fe9953b",
  //   "variationId": null,
  //   "mainProductId": "63bbbe56c1369e0039e5aa3c",
  //   "mainVariationId": "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

getCurrentThemeKey()

Get merchant current theme key.

Available Pages: all

Return Value:

A string that represents the merchant current theme key.

Example

themeKey = await sdk.utils.getCurrentThemeKey();

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

<details>
<summary>Click to expand</summary>

Your content here.

</details>

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:

  • main_product_id: A string that represents the (main) 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
  • variation_rendered: A boolean indicating whether the product has variations
  • variation_ids: An array of string of the product's variation IDs (null if no variation)
  • default_variation_id: A string of the variation ID matched from the URL variant_id (null if not matched)
  • id: (Deprecated) Same as main_product_id
  • variation_keys: (Deprecated, please use variation_ids instead.) An array of string of the product's variation IDs (empty array [] if no variation)
  • addon_product_rendered: A boolean indicating whether the product has add-on products
  • addon_product_ids: An array of string of the product's add-on product IDs (null if no add-on product)

Example:

product = await sdk.utils.getPDPProduct();

console.log(product);
// Output: {
//     "id": "63bbbe56c1369e0039e5aa3c",                  // Deprecated, same as main_product_id
//     "variation_keys": [                                 // Deprecated, same as variation_ids ([] if none)
//         "62d517722c015a00312c7df4",
//         "62d517722c015a00312c7df5"
//     ],
//     "main_product_id": "63bbbe56c1369e0039e5aa3c",
//     "tags": "tag1,tag2",
//     "category_ids": [
//         "62958abc38aec9003b96d538",
//         "6295b66cfe110a0035975a31"
//     ],
//     "variation_rendered": true,
//     "variation_ids": [
//         "62d517722c015a00312c7df4",
//         "62d517722c015a00312c7df5"
//     ],
//     "default_variation_id": "62d517722c015a00312c7df4",
//     "addon_product_rendered": true,
//     "addon_product_ids": [
//         "66589fb1e9bd62001fe9953b",
//         "66589fb1e9bd62001fe9953c"
//     ]
// }
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 cart 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 cart 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 13 days ago