BLOY Hydrogen SDK

Official SDK for integrating BLOY Loyalty widgets into Shopify Hydrogen and custom headless storefronts.

Features

• Loyalty Widget
• VIP Program
• Product Point Calculator
• Redeem Rewards on Cart
• Headless Authentication
• Theme Synchronization
• Shopify Hydrogen Support

Installation

npm install bloy-dong-hydrogen-sdk

or

yarn add bloy-dong-hydrogen-sdk

or

pnpm add bloy-dong-hydrogen-sdk

Requirements

• Shopify Hydrogen
• React 18+
• Shopify Storefront API
• BLOY Loyalty installed on Shopify

Environment Variables

Configure the following variables in Hydrogen:

PUBLIC_BLOY_CDN_URL=https://cdn.bloy.io
BLOY_API_URL=https://api.bloy.io
BLOY_CMS_URL=https://cms.bloy.io

# Secret provided by BLOY
BLOY_TOKEN_SECRET=xxxxxxxxxxxxxxxx

Setup

1. Load BLOY Data in Root Loader

import { getBloyConfigData } from 'bloy-dong-hydrogen-sdk';

async function loadCriticalData({ context }) {
  const { storefront, session, customerAccount } = context;

  let customer = null;

  if (await customerAccount.isLoggedIn()) {
    customer = await customerAccount.query(CUSTOMER_QUERY);
  }

  const header = await storefront.query(HEADER_QUERY);

  const shopDomain =
    header.shop.primaryDomain.url.replace('https://', '');

  const bloyData = await getBloyConfigData({
    storefront,
    session,
    env: context.env,
    shopDomain,
    customer: {
      id:
        customer?.data?.customer?.id?.replace(
          'gid://shopify/Customer/',
          '',
        ) || '',
      email:
        customer?.data?.customer?.emailAddress?.emailAddress || '',
    },
  });

  return {
    header,
    ...bloyData,
  };
}

2. Initialize BLOY

Inside root.jsx:

import { useRouteLoaderData } from 'react-router';
import { useBloyLoyalty } from 'bloy-dong-hydrogen-sdk';

export default function App() {
  const data = useRouteLoaderData('root');

  useBloyLoyalty(data);

  return <Outlet />;
}

The SDK automatically:

• Loads BLOY widgets
• Injects storefront theme settings
• Loads translations
• Loads loyalty configuration
• Synchronizes customer session
• Initializes headless storefront globals

3. Product Point Calculator

import { useBloyProductCalculator } from 'bloy-dong-hydrogen-sdk';

export default function Product() {
  const { product } = useLoaderData();

  useBloyProductCalculator({ product });

  return (
    <div className="BLOY-point-calculator__container" />
  );
}

4. Redeem Rewards on Cart

import { useBloyCart } from 'bloy-dong-hydrogen-sdk';

export default function Cart() {
  const { cart } = useLoaderData();

  useBloyCart({ cart });

  return (
    <div className="BLOY-cart__rewards" />
  );
}

Authentication

The SDK uses a two-step authentication process for headless storefronts.

Step 1

Generate a temporary configuration token:

HMAC_SHA256(
  shopDomain.customerId,
  BLOY_TOKEN_SECRET
)

Used to securely fetch storefront configuration.

Step 2

After configuration is loaded, the SDK generates a customer token:

HMAC_SHA256(
  shopId.customerId,
  BLOY_TOKEN_SECRET
)

Used by loyalty widgets to authenticate the customer.

No manual token generation is required by the merchant.

API Reference

getBloyConfigData()

Fetches BLOY storefront configuration.

Parameters

{
  storefront: any;
  session: any;
  env: any;
  shopDomain: string;
  customer?: {
    id?: string;
    email?: string;
  };
}

Returns

{
  bloy: {
    shopId: string;
    storeDomain: string;
    customer: {
      id: string;
      email: string;
      token: string;
    };
    cdnUrl: string;
    apiUrl: string;
    cmsUrl: string;
    headlessConfig: any;
  };
}

useBloyLoyalty()

useBloyLoyalty(data);

Initializes global BLOY widgets.

useBloyProductCalculator()

useBloyProductCalculator({
  product,
});

Initializes Product Point Calculator.

useBloyCart()

useBloyCart({
  cart,
});

Synchronizes Hydrogen cart data with BLOY Cart Widget.

Widget Containers

Product Calculator

<div class="BLOY-point-calculator__container"></div>

Cart Rewards

<div class="BLOY-cart__rewards"></div>

Troubleshooting

Widget does not appear

Verify:

```javascript
window.BloyConfigs.shop_id

contains a valid value.

Authentication failed

Verify:

BLOY_TOKEN_SECRET

matches the secret provided by the BLOY team.

Loader script not loaded

Verify:

PUBLIC_BLOY_CDN_URL

is configured correctly.

License

MIT