INTEGRATION WITH BOGOS JS/SDK

This page provides an overview of the key requirements for integration with the BOGOS app via the BOGOS JS/SDK. It is recommended to read this page thoroughly before proceeding to the next sections

1. Requirements

• Install BOGOS app: https://apps.shopify.com/freegifts

• Your store must be built using the Storefront API.

• Always create a cart after applying BOGOS to ensure the cart ID is received correctly. Example

• For advanced customization in your Headless store, refer to the BOGOS API documentation.

• Please refer to BOGOS' Demo store for all features demo: Demo store

If you need integration in a development environment, contact BOGOS via live chat or email at [e-mail]

2. Installation

Version source

  BOGOS_JS_SDK=https://cdn.bogos.io/bogos-app-ext/20251217-1765947613/core.min.js

Step 1: Getting started

1. Add the following script to your project:

   <script id="bogos-core" src={{BOGOS_JS_SDK}} defer
     data-storefront-api-token={{PUBLIC_STOREFRONT_API_TOKEN}}
     data-api-version={{PUBLIC_STOREFRONT_API_VERSION}}
     data-myshopify-domain={{MYSHOPIFY_DOMAIN}}
     data-bogos-key={{BOGOS_KEY}}
   />

   Property	Description	Example
   VERSION_SOURCE: String!	The script URL for the current version	https://cdn.bogos.io/{{version}}/core.min.js
   PUBLIC_STOREFRONT_API_TOKEN: String!	Public Storefront API token	abcd...
   PUBLIC_STOREFRONT_API_VERSION: String!	Storefront API version	2025-04
   MYSHOPIFY_DOMAIN: String!	Myshopify domain (found in Shopify Admin > Settings)	bogos.myshopify.com
   BOGOS_KEY: String!	Key generated by the BOGOS app	bogoskey...

   💡 Example Available 👉 root.tsx

2. Update your project with the required BOGOS data:

   typeof window !== 'undefined' && typeof window.BOGOS_CORE !== 'undefined' &&
     window.BOGOS_CORE?.helper?.updateCore(option: BOGOSOptions)

   export type BOGOSOptions = {
     cart?: Cart;
     customer?: string | Customer;
     locale?: string; https://shopify.dev/docs/api/storefront/latest#@inContext-(Language)
     country?: string; https://shopify.dev/docs/api/storefront/latest#@inContext-(Country-Code)
     currency?: {
       active: string;
       rate: number;
     };
     market?: {
       id: number;
       handle: string;
     }
   };

   Note:

   • You must provide at least one of the above properties.

   • If you provide the full Cart object, BOGOS will not fetch the cart again.

   • If only the Cart ID is provided, BOGOS will fetch the cart again.

   • The customer parameter can be either a customer access token or customer object

   💡 Example Available 👉 root.tsx 👉 Layout.tsx 👉 Cart.tsx

Step 2: Gift Offer

1. Trigger the gift logic whenever the cart is updated:

     typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent('bogos:gifts', { detail: cart }));

   Note:

   • cart: Cart

   • If you provide the full Cart, it won’t fetch again.

   • If only the Cart ID is provided, it will fetch again.

   💡 Example Available 👉 Cart.tsx

2. Add prepareCheckout to your checkout process to validate gift items before proceeding to checkout:

   async function {your_function_checkout} (args) {
       ...
       typeof window !== 'undefined' && typeof window.BOGOS_CORE !== 'undefined' &&
         await BOGOS_CORE?.helper?.gift?.prepareCheckout();
       ...
   }

   💡 Example Available 👉 Cart.tsx

3. Customize

   3.1. Gift Icon & Gift thumbnail

   • On the product page Add class "fg-secomapp-product-title" where you want to display gift icon Add class "bogos-gift-thumbnail-view" where you want to display gift thumbnail

   typeof window !== 'undefined' && window.BOGOS_CORE?.helper?.gift?.renderCustomizeForProduct([{ id: product_id }], { product: true });

   or

   // An event is triggered for all customizations on the product page
   typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
     detail: {
       products: [{ id: product_id }],
       options: { product: true, selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] }
     }
   }));

   💡 Example Available 👉 products.$handle.tsx

   • For collection page Add class "fg-secomapp-collection-img" to where you want to display gift icon on product card

   typeof window !== 'undefined' && window.BOGOS_CORE?.helper?.gift?.renderCustomizeForProduct([{ id: product.id }], { collection: true });

   💡 Example Available 👉 collections.$handle.tsx

   3.2. Cart message

   Add the class "bogos-cart-message-view" to the element where you want the message displayed

   <div class="bogos-cart-message-view"></div>

   3.3. Gift slider

   To embed the gift slider instead of displaying as a popup, include the following code:

   <div id="freegifts-main-page-container"></div>

Step 3: Bundle Offer

1. Classic bundle

   Add the following element to where you want to display the bundle offer.

     <div id="bogos-bundle-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>
   
     /* 
       product_id: number; legacy product id
       offer_id: number; BOGOS offer id
     */

   Dispatch this element to render the bundle offer

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-init"));

   or

   // An event is triggered for all customizations on the product page
   typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
     detail: {
       products: [{ id: product_id }],
       options: { 
         product?: true, 
         selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
       }
     }
   }));

   💡 Example Available 👉 products.$handle.tsx

2. Mix-match

   Add the following element to where you want to display the bundle offer.

     <div id="bogos-mix-match-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>
   
     /* 
       product_id: number; legacy product id
       offer_id: number; BOGOS offer id
     */

   Dispatch this element to show bundle offer

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-init"));

   or

   // An event is triggered for all customizations on the product page
   typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
     detail: {
       products: [{ id: product_id }],
       options: { 
         product?: true, 
         selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
       }
     }
   }));

   💡 Example Available 👉 products.$handle.tsx

Step 4: Bundle Page

Add the following element to where you want to display the bundle offer.

  <div id="bogos-bundle-page-view" data-offer-id={{offer_id}}></div>

  /* offer_id: number; BOGOS offer id */

Dispatch this element to render the bundle offer.

  typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:bundle-page-init"));

💡 Example Available 👉 bundle-page.$id.tsx

Step 5: Upsell Offer

1. Frequently Bought Together (FBT)

   Add the following element to where you want to display the upsell offer

     <div id="bogos-fbt-upsell-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>
   
     /* 
       product_id: number; legacy product id
       offer_id: number; BOGOS offer id
     */

   Dispatch this element to render the upsell offer

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:upsell-init"));

   💡 Example Available 👉 products.$handle.tsx

Step 6: Discount Offer

1. Volume Discount

   Add the following element to where you want to display the discount offer

     <div id="bogos-volume-discount-view" data-product-handle={{product_handle}} data-product-id={{product_id}} data-offer-id={{offer_id}}></div>
   
     /* 
       product_id: number; legacy product id
       offer_id: number; BOGOS offer id
     */

   Dispatch this element to render the discount offer

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:discount-init"));

   or

   // An event is triggered for all customizations on the product page
   typeof document !== 'undefined' && document.dispatchEvent(new CustomEvent("bogos:product-change", {
     detail: {
       products: [{ id: product_id }],
       options: { 
         product?: true, 
         selectedVariants?: [{ product_id: product_id, id: selected_variant_id }] 
       }
     }
   }));

   💡 Example Available 👉 products.$handle.tsx

Step 7: Booster

1. Progressing bar

   Add the following element to where you want to display the progressing bar

     <div class="bogos-progressing-bar-view" data-offer-id={{offer_id}}></div>
   
     /* 
       offer_id: number; BOGOS booster id
     */

   Dispatch this element to render the progressing bar

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:progress-rerender"));

   💡 Example Available 👉 Cart.tsx

2. Today offer

   Add the following element to where you want to display the today offer block

     <div class="bogos-to-block-view" data-offer-id={{offer_id}}></div>
   
     /* 
       offer_id: number; BOGOS booster id
     */

   Dispatch this element to render the today offer block and today offer widget

     typeof document !== "undefined" && document.dispatchEvent(new CustomEvent("bogos:to-widget-render"));

   💡 Example Available 👉 _index.tsx 👉 Cart.tsx

3. Other integrations

3. 1. Hide gift product (cloned product)

• If you use products query, you should add : query: "tag_not:bogos-gift"

products (
    ...,
    query: "tag_not:bogos-gift"
) {
...
}

• For collection and product page, you can import checkItemIsGift and use returned value to skip gift products or replace to other pages

export type ProductObject = {
    handle: string;
    tags: string[];
    variant_id: number;
};

/* item can be product handle */
checkItemIsGift: (item: string | ProductObject) => boolean;

💡 Example Available 👉 collections.$handle.tsx 👉 products.$handle.tsx

3.2. Customize gift popup/slider

• Hide all default gift slider elements, and override with your custom implementation.

  #freegifts-main-popup-container, #freegifts-main-page-container {
    display: none !important;
  }

type GiftItem = {
    id: number;
    discount_type: 'percentage' | 'fixed_amount';
    discount_value: number;
    original_price: number;  // Original price - price before discount
    price: number;           // Discount price - price after discount
    title: string;
    thumbnail?: string;
};

type GiftProduct = {
    id: number;
    title: string;
    handle: string;
    thumbnail?: string;
    belongs_to_offer: string;
    variants: GiftItem[];
};

document.addEventListener("fg-gifts:show-slider", (e) => {
    console.log((e as CustomEvent).detail);
    /* render gift slider with detail {
        addGiftToCartFunc: (variant_id: number, quantity: number, offer_id: number) => {};
        gifts?: GiftProduct[]; // show all gifts
        giftsOffer?: { // show gifts by offer
          arrGiftShow: GiftProduct[];
        }
    } */
});

3.3. Details of additional event listeners

• fg-gifts:updated: Event gift is updated in cart

document.addEventListener("fg-gifts:updated", (e) => {
    /* use this function to re-render cart */
    console.log((e as CustomEvent).detail);
});

💡 Example Available 👉 Layout.tsx

• fg-cart:auto-updated: Event gift auto add

document.addEventListener("fg-cart:auto-updated", (e) => {
    console.log((e as CustomEvent).detail);
});

• fg-gifts:added: Event add gift from slider, will not work if you customize gifts popup

document.addEventListener("fg-gifts:added", (e) => {
    console.log((e as CustomEvent).detail);
});

• fg-gifts:gift-icon: Show gift icons

• bogos:message: Show cart message

4. Note

For deeper customization, please contact our support team via live chat or email - [e-mail]

4.1. Publish Gift/Cloned Products

• After creating or editing an offer, ensure that the gift/cloned product is published to your Headless channel (or any channel where you want BOGOS to run).

4.2. Some features are not yet available in this version

• Draft-Order API

• Automatic volume discount

• Bundle page button block

• Some Shopify object-based params (if only id provided, BOGOS will fetch the rest).