Skip to content

Configuration de l’intégration personnalisée de Shopify

Cette page vous explique comment intégrer Braze à une boutique Shopify Hydrogen ou à n’importe quelle boutique Shopify headless en utilisant une vitrine personnalisée.

Ce guide utilise le framework Hydrogen de Shopify comme exemple. Cependant, vous pouvez suivre une approche similaire si votre marque utilise Shopify pour le backend de votre boutique avec une configuration front-end « headless ».

Pour intégrer votre boutique Shopify headless à Braze, vous devez remplir ces deux objectifs :

  1. Initialiser et charger le SDK Web de Braze pour permettre le suivi sur site

    Ajoutez manuellement du code dans votre site Shopify pour activer le suivi sur site de Braze. En implémentant le SDK de Braze sur votre boutique Shopify headless, vous pouvez suivre les activités sur site, notamment les sessions, le comportement des utilisateurs anonymes, les actions des acheteurs avant le passage en caisse, ainsi que tout événement personnalisé ou attribut personnalisé que vous choisissez d’inclure avec votre équipe de développement. Vous pouvez également ajouter tous les canaux pris en charge par les SDK, tels que les In-App Messages ou Content Cards.
  1. Installer l’intégration Braze pour Shopify

    Après avoir connecté votre boutique Shopify à Braze, vous aurez accès aux données des clients, des paiements, des commandes et des produits grâce aux webhooks de Shopify.

Pour atteindre ces objectifs, suivez les étapes suivantes :

Initialiser et charger le SDK Web de Braze

Étape 1 : Sélectionner une application de site web et copier les identifiants du SDK

Avant d’ajouter du code à votre vitrine Hydrogen, connectez votre boutique Shopify et démarrez l’onboarding de configuration personnalisée. Si vous n’avez pas encore connecté votre boutique, suivez les instructions dans Connecter votre boutique Shopify, puis continuez avec Activer les SDK Braze et sélectionnez Custom setup.

Dans le flux de configuration personnalisée, Braze vous invite à sélectionner l’application de site web pour votre vitrine headless :

  1. Sélectionnez une application de site web existante ou créez-en une nouvelle. Vous pouvez nommer l’application comme vous le souhaitez, sauf Shopify, nom que Braze réserve au parcours d’intégration Shopify standard.
  2. Braze affiche la clé API et l’URL de base (votre endpoint SDK) de l’application sélectionnée dans l’étape d’onboarding. Sélectionnez Copy pour chaque valeur — vous n’avez pas besoin d’ouvrir Settings > App Settings.
  3. Utilisez la clé API copiée comme BRAZE_API_KEY et l’endpoint SDK comme BRAZE_API_URL dans vos variables d’environnement Shopify (Étape 2).

Après avoir connecté la boutique, vous pouvez renommer l’application de site web sélectionnée dans Settings > App Settings. Vous ne pouvez pas supprimer l’application tant qu’elle est connectée à votre intégration Shopify.

Étape 2 : Ajouter le sous-domaine et les variables d’environnement

  1. Configurez votre sous-domaine Shopify pour rediriger le trafic de votre boutique en ligne vers Hydrogen.
  2. Ajoutez un URI de rappel pour la connexion. (L’URI sera automatiquement ajouté lorsque le domaine sera ajouté.)
  3. Configurez vos variables d’environnement Shopify :
    • Créez deux variables d’environnement en utilisant la clé API et l’endpoint SDK que vous avez copiés lors de l’onboarding de configuration personnalisée à l’Étape 1.
    • BRAZE_API_KEY
    • BRAZE_API_URL

Étape 3 : Activer le suivi sur site

La première étape consiste à initialiser le SDK Web de Braze. Nous recommandons de le faire en installant notre package NPM :

1
2
3

npm install --save @braze/web-sdk@6.8.0
# or, using yarn:
# yarn add @braze/web-sdk

Ensuite, incluez ce paramètre comme clé de premier niveau dans votre fichier vite.config.js :

1
2
3

optimizeDeps: {
    exclude: ['@braze/web-sdk']
}

Après avoir installé le package NPM, vous devez initialiser le SDK dans un hook useEffect à l’intérieur du composant Layout. Selon votre version de Hydrogen, ce composant peut se trouver dans le fichier root.jsx ou layout.jsx :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Add these imports
import * as braze from "@braze/web-sdk";
import { useEffect } from 'react';

export function Layout({children}) {
  const nonce = useNonce();
  // @type {RootLoader}
  const data = useRouteLoaderData('root');

  // Add useEffect call to initialize Braze SDK
  useEffect(() => {
    if(!braze.isInitialized()) {
      braze.initialize(data.brazeApiKey, {
        baseUrl: data.brazeApiUrl,
      });
      braze.openSession()
    }
  }, [data])

  return (...);
}

Les valeurs data.brazeApiKey et data.brazeApiUrl doivent être incluses dans le loader du composant en utilisant les variables d’environnement créées à l’Étape 2 :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

export async function loader(args) {
  // Start fetching non-critical data without blocking time to first byte
  const deferredData = loadDeferredData(args);

  // Await the critical data required to render initial state of the page
  const criticalData = await loadCriticalData(args);

  const {storefront, env} = args.context;

  return {
    ...deferredData,
    ...criticalData,
    publicStoreDomain: env.PUBLIC_STORE_DOMAIN,
    // Add the two properties below to the returned value
    brazeApiKey: env.BRAZE_API_KEY,
    brazeApiUrl: env.BRAZE_API_URL,
    shop: getShopAnalytics({
      storefront,
      publicStorefrontId: env.PUBLIC_STOREFRONT_ID,
    }),
    consent: {
      checkoutDomain: env.PUBLIC_CHECKOUT_DOMAIN,
      storefrontAccessToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      withPrivacyBanner: false,
      // Localize the privacy banner
      country: args.context.storefront.i18n.country,
      language: args.context.storefront.i18n.language,
    },
  };
}

Étape 4 : Ajouter un événement de connexion au compte Shopify

Suivez le moment où un acheteur se connecte à son compte et synchronise ses informations utilisateur avec Braze. Cela inclut l’appel à notre méthode changeUser pour identifier les clients avec un ID externe Braze.

Avant de commencer, assurez-vous d’avoir configuré les URI de rappel pour que la connexion client fonctionne dans Hydrogen. Pour plus d’informations, consultez Using the Customer Account API with Hydrogen.

  1. Après avoir configuré les URI de rappel, définissez une fonction pour appeler le SDK Braze. Créez un nouveau fichier (tel que Tracking.jsx) et importez-le depuis vos composants :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import * as braze from "@braze/web-sdk";

export function trackCustomerLogin(customerData, storefrontUrl) {
  const customerId = customerData.id.substring(customerData.id.lastIndexOf('/') + 1)
  const customerSessionKey = `ab.shopify.shopify_customer_${customerId}`;
  const alreadySetCustomerInfo = sessionStorage.getItem(customerSessionKey);

  if(!alreadySetCustomerInfo) {
    const user = braze.getUser()

    // To use Shopify customer ID as Braze External ID, use:
    // braze.changeUser(customerId)

    // To use Shopify customer email as Braze External ID, use:
      // braze.changeUser(customerData.emailAddress?.emailAddress)
        // To use hashing for email addresses, apply hashing before calling changeUser

    // To use your own custom ID as the Braze External ID, pass that value to the changeUser call.

    user.setFirstName(customerData.firstName);
    user.setLastName(customerData.lastName);
    if(customerData.emailAddress.emailAddress) {
      user.setEmail(customerData.emailAddress?.emailAddress);
    }

    if(customerData.phoneNumber?.phoneNumber) {
      user.setPhoneNumber(customerData.phoneNumber?.phoneNumber);
    }
    braze.logCustomEvent(
      "shopify_account_login",
      { source: storefrontUrl }
    )
    sessionStorage.setItem(customerSessionKey, customerId);
  }
}
  1. Dans le même hook useEffect qui initialise le SDK Braze, ajoutez l’appel à cette fonction :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import { trackCustomerLogin } from './Tracking';

export function Layout({children}) {
  const nonce = useNonce();
  // @type {RootLoader}
  const data = useRouteLoaderData('root');

  useEffect(() => {
    if(!braze.isInitialized()) {
      braze.initialize(data.brazeApiKey, {
        baseUrl: data.brazeApiUrl,
        enableLogging: true,
      });
      braze.openSession()
    }

    // Add call to trackCustomerLogin function
    data.isLoggedIn.then((isLoggedIn) => {
      if(isLoggedIn) {
        trackCustomerLogin(data.customerData, data.publicStoreDomain)
      }
    })

  }, [data])
  1. Récupérez l’adresse e-mail et le numéro de téléphone du client dans votre requête GraphQL de l’API Customer, située dans le fichier app/graphql/customer-account/CustomerDetailsQuery.js :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

export const CUSTOMER_FRAGMENT = `#graphql
  fragment Customer on Customer {
    id
    firstName
    lastName
    emailAddress {
      emailAddress
    }
    phoneNumber {
      phoneNumber
    }
    defaultAddress {
      ...Address
    }
    addresses(first: 6) {
      nodes {
        ...Address
      }
    }
  }
  fragment Address on CustomerAddress {
    id
    formatted
    firstName
    lastName
    company
    address1
    address2
    territoryCode
    zoneCode
    city
    zip
    phoneNumber
  }
`;
  1. Enfin, chargez les données client dans votre fonction loader :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// Add import for GraphQL Query
import { CUSTOMER_DETAILS_QUERY } from './graphql/customer-account/CustomerDetailsQuery';

export async function loader(args) {
  // Start fetching non-critical data without blocking time to first byte
  const deferredData = loadDeferredData(args);

  // Await the critical data required to render initial state of the page
  const criticalData = await loadCriticalData(args);

  const {storefront, env} = args.context;

  // Add GraphQL call to Customer API
  const isLoggedIn = await deferredData.isLoggedIn;
  let customerData;
  if (isLoggedIn) {
    const { data, errors } = await args.context.customerAccount.query(
        CUSTOMER_DETAILS_QUERY,
    );
    customerData = data.customer
  } else {
    customerData = {}
  }

  return {
    ...deferredData,
    ...criticalData,
    publicStoreDomain: env.PUBLIC_STORE_DOMAIN,
    brazeApiKey: env.BRAZE_API_KEY,
    brazeApiUrl: env.BRAZE_API_URL,
    // Add the property below to the returned value
    customerData: customerData,
    shop: getShopAnalytics({
      storefront,
      publicStorefrontId: env.PUBLIC_STOREFRONT_ID,
    }),
    consent: {
      checkoutDomain: env.PUBLIC_CHECKOUT_DOMAIN,
      storefrontAccessToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      withPrivacyBanner: false,
      // Localize the privacy banner
      country: args.context.storefront.i18n.country,
      language: args.context.storefront.i18n.language,
    },
  };
}

Étape 5 : Ajouter le suivi des événements Product Viewed et Cart Updated

Événements Product Viewed

  1. Ajoutez cette fonction à votre fichier Tracking.jsx :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

export function trackProductViewed(product, storefrontUrl) {
  const eventData = {
    product_id: product.id.substring(product.id.lastIndexOf('/') + 1),
    product_name: product.title,
    variant_id: product.selectedOrFirstAvailableVariant.id.substring(product.selectedOrFirstAvailableVariant.id.lastIndexOf('/') + 1),
    image_url: product.selectedOrFirstAvailableVariant.image?.url,
    product_url: `${storefrontUrl}/products/${product.handle}`,
    price: product.selectedOrFirstAvailableVariant.price.amount,
    currency: product.selectedOrFirstAvailableVariant.price.currencyCode,
    source: storefrontUrl,
    type: ["price_drop", "back_in_stock"],
    metadata: {
    sku: product.selectedOrFirstAvailableVariant.sku
  }

  }
  braze.logCustomEvent(
    "ecommerce.product_viewed",
    eventData
  )
}
  1. Pour appeler la fonction précédente chaque fois qu’un utilisateur visite une page produit, ajoutez un hook useEffect au composant Product dans le fichier app/routes/products.$handle.jsx :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import { trackProductViewed } from '~/tracking';
import { useEffect } from 'react';

export default function Product() {
  // @type {LoaderReturnData}
  // retrieve storefrontUrl to be passed into trackProductViewed
  const {product, storefrontUrl} = useLoaderData();

  // Add useEffect hook for tracking product_viewed event
  useEffect(() => {
    trackProductViewed(product, storefrontUrl)
  }, [])

  return (...)
}
  1. Ajoutez la valeur pour « storefrontUrl » (car elle n’est pas dans le loader du composant par défaut) :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

async function loadCriticalData({context, params, request}) {
  const {handle} = params;
  const {storefront} = context;

  if (!handle) {
    throw new Error('Expected product handle to be defined');
  }

  const [{product}] = await Promise.alll([
    storefront.query(PRODUCT_QUERY, {
      variables: {handle, selectedOptions: getSelectedProductOptions(request)},
    }),
    // Add other queries here, so that they are loaded in parallel
  ]);

  if (!product?.id) {
    throw new Response(null, {status: 404});
  }

  return {
    product,
   // Add this property to the returned value
    storefrontUrl: context.env.PUBLIC_STORE_DOMAIN,
  };
}

Événements Cart Updated

  1. Définissez des fonctions pour le suivi de l’événement cart_updated et la définition du jeton de panier :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

export function trackCartUpdated(cart, storefrontUrl) {
  const eventData = {
    cart_id: cart.id,
    total_value: cart.cost.totalAmount.amount,
    currency: cart.cost.totalAmount.currencyCode,

    products: cart.lines.nodes.map((line) => {
      return {
        product_id: line.merchandise.product.id.toString(),
        product_name: line.merchandise.product.title,
        variant_id: line.merchandise.id.toString(),
        image_url: line.merchandise.image.url,
        product_url: `${storefrontUrl}/products/${line.merchandise.product.handle}`,
        quantity: Number(line.quantity),
        price: Number(line.cost.totalAmount.amount / Number(line.quantity))
      }
    }),
    source: storefrontUrl,
    metadata: {},
  };

  braze.logCustomEvent(
    "ecommerce.cart_updated",
    eventData
  )
}

export function setCartToken(cart) {
  const cartId = cart.id.substring(cart.id.lastIndexOf('/') + 1)
  const cartToken = cartId.substring(0, cartId.indexOf("?key="));
  if (cartToken) {
    const cartSessionKey = `ab.shopify.shopify_cart_${cartToken}`;
    const alreadySetCartToken = sessionStorage.getItem(cartSessionKey);

    if (!alreadySetCartToken) {
      braze.getUser().addAlias("shopify_cart_token", `shopify_cart_${cartToken}`)
      braze.requestImmediateDataFlush();
      sessionStorage.setItem(cartSessionKey, cartToken);
    }
  }
}
  1. Renvoyez l’objet cart depuis l’action du fetcher afin que Braze puisse accéder à ses propriétés en vous rendant dans votre fichier app/routes/cart.jsx et en ajoutant ce qui suit à la fonction action :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

export async function action({request, context}) {
  const {cart} = context;

  ...

  switch (action) {
    case CartForm.ACTIONS.LinesAdd:
      result = await cart.addLines(inputs.lines);
      break;
    ...
  }

  const cartId = result?.cart?.id;
  const headers = cartId ? cart.setCartId(result.cart.id) : new Headers();
  const {cart: cartResult, errors, warnings} = result;

  const redirectTo = formData.get('redirectTo') ?? null;
  if (typeof redirectTo === 'string') {
    status = 303;
    headers.set('Location', redirectTo);
  }

  return data(
    {
      cart: cartResult,
      // Add these two properties to the returned value
      updatedCart: await cart.get(),
      storefrontUrl: context.env.PUBLIC_STORE_DOMAIN,
      errors,
      warnings,
      analytics: {
        cartId,
      },
    },
    {status, headers},
  );
}

Pour plus d’informations sur les fetchers Remix, consultez useFetcher.

  1. Les boutiques Hydrogen définissent généralement un composant CartForm qui gère l’état de l’objet panier, utilisé lors de l’ajout, la suppression et la modification de la quantité d’articles dans un panier. Ajoutez un autre hook useEffect dans le composant AddToCartButton qui appellera la fonction trackCartUpdated chaque fois que l’état du fetcher du formulaire change (chaque fois que le panier de l’utilisateur est mis à jour) :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// Add imports
import { trackCartUpdated, setCartToken } from '~/tracking';
import { useEffect } from 'react';
import { useFetcher } from '@remix-run/react';

export function AddToCartButton({
  analytics,
  children,
  disabled,
  lines,
  onClick,
}) {

  // Define a new Fetcher to be used for tracking cart updates
  const fetcher = useFetcher({ key: "cart-fetcher" });

  // Add useEffect hook for tracking cart_updated event and setting cart token alias
  useEffect(() => {
    if(fetcher.state === "idle" && fetcher.data) {
      trackCartUpdated(fetcher.data.updatedCart, fetcher.data.storefrontUrl)
      setCartToken(fetcher.data.updatedCart);
    }
  }, [fetcher.state, fetcher.data])

  // Add the fetcherKey prop to the CartForm component
  return (
    <CartForm route="/cart" inputs= fetcherKey="cart-fetcher" action={CartForm.ACTIONS.LinesAdd}>
      {(fetcher) => (
        <>
          <input
            name="analytics"
            type="hidden"
            value={JSON.stringify(analytics)}
          />
          <button
            type="submit"
            onClick={onClick}
            disabled={disabled ?? fetcher.state !== 'idle'}
          >
            {children}
          </button>
        </>
      )}
    </CartForm>
  );
}
  1. Utilisez le même fetcherKey pour les actions responsables de la mise à jour d’un produit existant dans votre panier. Ajoutez ce qui suit aux composants CartLineRemoveButton et CartLineUpdateButton (situés par défaut dans le fichier app/components/CartLineItem.jsx) :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

function CartLineRemoveButton({lineIds, disabled}) {
  // Add the fetcherKey prop to the CartForm component
  return (
    <CartForm
      fetcherKey="cart-fetcher"
      route="/cart"
      action={CartForm.ACTIONS.LinesRemove}
      inputs=
    >
      <button disabled={disabled} type="submit">
        Remove
      </button>
    </CartForm>
  );
}

function CartLineUpdateButton({children, lines}) {
  // Add the fetcherKey prop to the CartForm component
  return (
    <CartForm
      route="/cart"
      fetcherKey="cart-fetcher"
      action={CartForm.ACTIONS.LinesUpdate}
      inputs=
    >
      {children}
    </CartForm>
  );
}

Installer l’intégration Braze Shopify

Étape 1 : Connecter votre boutique Shopify

Accédez à la page partenaire Shopify pour commencer la configuration. Commencez par sélectionner Commencer la configuration pour installer l’application Braze depuis le Shopify App Store. Suivez les étapes guidées pour terminer le processus d’installation.

Page de configuration de l'intégration Shopify sur le tableau de bord de Braze.

Étape 2 : Activer les SDK Braze

Pour les boutiques Shopify Hydrogen ou headless, sélectionnez l’option Configuration personnalisée.

La configuration personnalisée comprend un sélecteur d’application web. Sélectionnez ou créez l’application qui alimente votre vitrine, puis copiez la clé API et l’endpoint SDK affichés dans l’étape d’onboarding. Pour plus de détails, consultez Étape 1 : Sélectionner une application web et copier les identifiants SDK.

Avant de poursuivre le processus d’onboarding, confirmez que vous avez ajouté le SDK Braze à votre site Shopify en utilisant ces identifiants.

Étape de configuration pour activer les SDK Braze.

Étape 3 : Suivre les données Shopify

Enrichissez votre intégration en ajoutant davantage d’événements et d’attributs Shopify, qui seront alimentés par les webhooks Shopify. Pour des informations détaillées sur les données suivies via cette intégration, consultez Fonctionnalités de données Shopify.

Étape de configuration pour suivre les données Shopify.

Étape 4 : Remplissage historique (facultatif)

Via la configuration personnalisée, vous pouvez optionnellement inclure le même chargement de données historiques Shopify que l’intégration standard : les événements de commande des 90 derniers jours et les profils utilisateur de l’année écoulée, chacun comptabilisé à partir de la date à laquelle vous finalisez votre intégration. Pour inclure ce chargement initial de données, cochez la case correspondante.

Si vous préférez effectuer le remplissage ultérieurement, vous pouvez terminer la configuration initiale maintenant et revenir à cette étape plus tard.

Section pour configurer le remplissage historique des données.

Pour la liste complète des données du chargement initial, le comportement de reporting des revenus et le suivi de la synchronisation, consultez Remplissage historique.

Étape 5 : Configuration du suivi de données personnalisées (avancé)

Avec les SDK Braze, vous pouvez suivre des événements personnalisés ou des attributs personnalisés qui vont au-delà des données prises en charge par cette intégration. Les événements personnalisés capturent des interactions uniques dans votre boutique, tels que :

Étape 5 : Configuration du suivi de données personnalisées (avancé)
Événements personnalisés Attributs personnalisés
  • Utilisation d'un code de réduction personnalisé
  • Interaction avec une recommandation produit personnalisée
  • Marques ou produits favoris
  • Catégories d'achat préférées
  • Statut d'adhésion ou de fidélité

Le SDK doit être initialisé (à l’écoute de l’activité) sur l’appareil de l’utilisateur pour enregistrer des événements ou des attributs personnalisés. Pour en savoir plus sur l’enregistrement de données personnalisées, consultez User object et logCustomEvent.

Étape 6 : Configurer la gestion des utilisateurs (facultatif)

Sélectionnez votre type d’external_id dans le menu déroulant.

Section « Collecter les abonnés ».

Par défaut, Braze convertit automatiquement les e-mails provenant de Shopify en minuscules avant de les utiliser comme ID externe. Si vous utilisez l’e-mail ou l’e-mail haché comme ID externe, vérifiez que vos adresses e-mail sont également converties en minuscules avant de les attribuer comme ID externe ou avant de les hacher à partir d’autres sources de données. Cela permet d’éviter les divergences d’ID externes et la création de profils utilisateur en double dans Braze.

Étape 6.1 : Créer le métachamp braze.external_id

  1. Dans votre panneau d’administration Shopify, accédez à Paramètres > Métachamps.
  2. Sélectionnez Clients > Ajouter une définition.
  3. Pour Namespace and key, saisissez braze.external_id.
  4. Pour Type, sélectionnez ID Type.

Une fois le métachamp créé, remplissez-le pour vos clients. Nous recommandons les approches suivantes :

  • Écouter les webhooks de création de clients : Configurez un webhook pour écouter les événements customer/create. Cela vous permet d’écrire le métachamp lorsqu’un nouveau client est créé.
  • Remplir rétroactivement les clients existants : Utilisez l’Admin API ou la Customer API pour remplir rétroactivement le métachamp pour les clients précédemment créés.

Étape 6.2 : Créer un endpoint pour récupérer votre ID externe

Vous devez créer un endpoint public que Braze peut appeler pour récupérer l’ID externe. Cela permet à Braze de récupérer l’ID dans les scénarios où Shopify ne peut pas fournir directement le métachamp braze.external_id.

Spécifications de l’endpoint

Méthode : GET

Braze envoie les paramètres suivants à votre endpoint :

Paramètre Obligatoire Type de données Description
shopify_customer_id Oui String L’ID client Shopify.
shopify_storefront Oui String Le nom de la vitrine pour la requête. Ex : <storefront_name>.myshopify.com
email_address Non String L’adresse e-mail de l’utilisateur connecté.

Ce champ peut être absent dans certains scénarios de webhook. La logique de votre endpoint doit prendre en compte les valeurs nulles ici (par exemple, récupérer l’e-mail en utilisant le shopify_customer_id si votre logique interne l’exige).
Exemple d’endpoint
1

GET https://mystore.com/custom_id?shopify_customer_id=1234&[email protected]&shopify_storefront=dev-store.myshopify.com
Réponse attendue

Braze attend un code de statut 200 renvoyant l’ID externe en JSON :

1
2
3

{
  "external_id": "my_external_id"
}
Validation

Il est essentiel de valider que le shopify_customer_id et l’email_address (si présente) correspondent aux valeurs du client dans Shopify. Vous pouvez utiliser la Shopify Admin API ou la Customer API pour valider ces paramètres et récupérer le bon métachamp braze.external_id.

Comportement en cas d’échec et fusion

Tout code de statut autre que 200 est considéré comme un échec.

  • Implications de la fusion : si l’endpoint échoue (renvoie un code autre que 200 ou expire), Braze ne peut pas récupérer l’ID externe. Par conséquent, la fusion entre l’utilisateur Shopify et le profil utilisateur Braze ne se produit pas à ce moment-là.
  • Logique de nouvelle tentative : Braze peut effectuer des tentatives réseau immédiates standard, mais si l’échec persiste, la fusion est reportée jusqu’au prochain événement éligible (par exemple, la prochaine fois que l’utilisateur met à jour son profil ou finalise un paiement).
  • Prise en charge : pour garantir une fusion rapide des utilisateurs, assurez-vous que votre endpoint est hautement disponible et gère correctement le champ optionnel email_address.

Étape 6.3 : Saisir votre ID externe

Répétez l’étape 6, puis saisissez l’URL de votre endpoint après avoir sélectionné l’ID externe personnalisé comme type d’ID externe Braze.

Considérations
  • Si votre ID externe n’est pas généré lorsque Braze envoie une requête à votre endpoint, l’intégration utilisera par défaut l’ID client Shopify lorsque la fonction changeUser est appelée. Cette étape est essentielle pour fusionner le profil utilisateur anonyme avec le profil utilisateur identifié. Par conséquent, il peut y avoir une période temporaire pendant laquelle différents types d’ID externes coexistent dans votre espace de travail.
  • Lorsque l’ID externe est disponible dans le métachamp braze.external_id, l’intégration donnera la priorité à cet ID externe et l’attribuera.
    • Si l’ID client Shopify a été précédemment défini comme ID externe Braze, il sera remplacé par la valeur du métachamp braze.external_id.

Étape 6.4 : Collecter les consentements e-mail ou SMS depuis Shopify (facultatif)

Vous avez la possibilité de collecter les consentements marketing par e-mail ou SMS depuis Shopify.

Si vous utilisez les canaux e-mail ou SMS, vous pouvez synchroniser les états de consentement marketing e-mail et SMS dans Braze. Si vous synchronisez les consentements marketing par e-mail depuis Shopify, Braze créera automatiquement un groupe d’abonnement e-mail pour tous les utilisateurs associés à cette boutique spécifique. Vous devez créer un nom unique pour ce groupe d’abonnement.

Section « Collecter les abonnés » avec l'option de collecter les consentements marketing par e-mail ou SMS.

Étape 7 : Synchroniser les produits (facultatif)

Vous pouvez synchroniser tous les produits de votre boutique Shopify vers un catalogue Braze pour une personnalisation approfondie de vos messages. Les mises à jour automatiques s’effectuent en quasi temps réel afin que votre catalogue reflète toujours les derniers détails des produits. Pour en savoir plus, consultez Synchronisation de produits Shopify.

Étape de configuration pour synchroniser les données produits vers Braze.

Étape 8 : Activer les canaux

Pour activer les In-App Messages, les Content Cards et les Feature Flags via l’intégration directe Shopify, ajoutez chaque canal à votre SDK. Suivez les liens de documentation fournis pour chaque canal :

  • In-App Messages : Pour activer les In-App Messages dans les cas d’usage de formulaires de capture de prospects, consultez In-App Messages.
  • Content Cards : Pour activer les Content Cards dans les cas d’usage de boîte de réception ou de bannières sur le site, consultez Content Cards.
  • Feature Flags : Pour activer les Feature Flags dans les cas d’usage d’expérimentation sur le site, consultez Feature Flags.

Étape 9 : Finaliser la configuration

Après avoir complété toutes les étapes, sélectionnez Terminer la configuration pour revenir à la page partenaire. Ensuite, activez l’intégration de l’application Braze dans votre page d’administration Shopify, comme indiqué par la bannière affichée.

Bannière indiquant d'activer l'intégration de l'application Braze dans Shopify pour finaliser la configuration de votre intégration.

Exemple de code

shopify-hydrogen-example est un exemple d’application Hydrogen contenant tout le code abordé dans les étapes précédentes.
New Stuff!