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.

2. 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.

Important

Avant de commencer votre intégration, vérifiez que vous avez correctement configuré le sous-domaine de paiement pour votre vitrine Shopify. Pour plus d’informations, consultez Migrer de la boutique en ligne vers Hydrogen.

Si cette configuration n’est pas effectuée correctement, Braze ne pourra pas traiter les webhooks de paiement de Shopify. Il ne sera pas non plus possible de tester l’intégration dans un environnement de développement local, car cela nécessite un domaine partagé entre votre vitrine et la page de paiement.

Pour atteindre ces objectifs, suivez les étapes suivantes :

Initialiser et charger le SDK Web de Braze

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

Avant d’ajouter du code à votre storefront Hydrogen, connectez votre boutique Shopify et lancez l’onboarding de configuration personnalisée. Si vous n’avez pas encore connecté votre boutique, suivez la procédure 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 web pour votre storefront headless :

1. Sélectionnez une application web existante ou créez-en une nouvelle. Vous pouvez nommer l’application comme vous le souhaitez, sauf Shopify, qui est réservé par Braze pour le 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 — il n’est pas nécessaire 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 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.

Avertissement

Utilisez la clé API de l’application web que vous avez sélectionnée lors de l’onboarding. Si votre environnement Hydrogen utilise une clé API différente de celle connectée à votre intégration Shopify, Braze risque de créer des utilisateurs en double et les méthodes du SDK pourraient ne pas fonctionner comme prévu.

Étape 2 : Ajouter un sous-domaine et des 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

Important

La version minimale prise en charge du SDK Web de Braze est la 5.4.0. Pour les intégrations Shopify personnalisées (y compris les storefronts headless), vous recevez des notifications lorsque de nouvelles versions du SDK sont disponibles, mais vous gérez les mises à jour de votre côté en mettant à jour à la fois le code de votre storefront et la version du SDK dans les paramètres d’intégration.

Ensuite, incluez ce paramètre en tant que 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 d’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 chargeur 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,
    },
  };
}

Remarque

Les politiques de sécurité du contenu (généralement situées dans le fichier Hydrogen entry.server.jsx) peuvent avoir un impact sur le fonctionnement des scripts Braze dans les environnements locaux et de production. Nous vous suggérons de tester via des builds de prévisualisation envoyés à Shopify via Oxygen ou des déploiements personnalisés. Si vous rencontrez des problèmes, vous devrez configurer votre CSP pour autoriser le fonctionnement de notre JavaScript.

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

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

Remarque

Nous n’avons actuellement pas de recommandations pour prendre en charge un ID externe Braze personnalisé. Si vous en avez besoin pour votre intégration maintenant, contactez votre gestionnaire de la satisfaction client.

Avant de commencer, assurez-vous d’avoir configuré les URI de rappel pour que la connexion client fonctionne avec 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);
  }
}

2. 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])

3. 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
  }
`;

4. Enfin, chargez les données client dans votre fonction de chargement :

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
  )
}

2. 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 (...)
}

3. Ajoutez la valeur pour « storefrontUrl » (car elle n’est pas incluse dans le chargeur 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

Important

Pour cette intégration, l’alias d’utilisateur doit respecter le format suivant afin que Braze puisse associer les webhooks au profil utilisateur correspondant :

• alias_label : shopify_cart_${cartToken}
• alias_name : shopify_cart_token

1. Définissez des fonctions pour le suivi de l’événement cart_updated et la configuration 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);
    }
  }
}

2. Retournez l’objet cart depuis l’action du fetcher afin que Braze puisse accéder à ses propriétés en allant 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.

3. 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, de la suppression et de 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 de 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>
  );
}

4. Utilisez le même fetcherKey pour les actions responsables de la mise à jour d’un produit existant depuis 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

Rendez-vous sur la page partenaire Shopify pour commencer votre 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.

É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 lors de l’étape d’onboarding. Pour plus de détails, consultez l’é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 web Shopify en utilisant ces identifiants.

É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 par cette intégration, consultez les fonctionnalités de données Shopify.

Étape 4 : Remplissage historique (facultatif)

Via la configuration personnalisée, vous pouvez inclure en option 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 calculé à partir de la date à laquelle vous avez finalisé votre intégration. Pour inclure ce chargement initial de données, cochez la case correspondante à l’option de chargement initial.

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

Pour la liste complète des données du chargement initial, le comportement des rapports de 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, telles que :

Le SDK doit être initialisé (en écoute d’activité) sur l’appareil d’un 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.

Important

L’utilisation d’une adresse e-mail ou d’une adresse e-mail hachée comme ID externe Braze peut aider à simplifier la gestion des identités à travers vos sources de données. Cependant, il est important de considérer les risques potentiels pour la confidentialité des utilisateurs et la sécurité des données.

• Informations devinables : les adresses e-mail sont facilement devinables, ce qui les rend vulnérables aux attaques.
• Risque d’exploitation : si un utilisateur malveillant modifie son navigateur web pour envoyer l’adresse e-mail d’une autre personne comme ID externe, il pourrait potentiellement accéder à des messages sensibles ou à des informations de compte.

Par défaut, Braze convertit automatiquement les e-mails 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 dans les ID externes et la création de profils utilisateur en double dans Braze.

Remarque

Les étapes suivantes dépendent de votre sélection d’ID externe :

• Si vous avez sélectionné un type d’ID externe personnalisé : complétez les étapes 6.1 à 6.3 pour configurer votre ID externe personnalisé.
• Si vous avez sélectionné l’ID client Shopify, l’e-mail ou l’e-mail haché : passez directement à l’étape 6.4 en ignorant les étapes 6.1 à 6.3.

É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éé, renseignez-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 lors de la création d’un nouveau client.
• Remplissage des clients existants : utilisez l’Admin API ou l’API Customer pour renseigner le métachamp des clients créés précédemment.

É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 :

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 au format 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 l’API Admin Shopify ou l’API Customer pour valider ces paramètres et récupérer le métachamp braze.external_id correct.

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

Reprenez l’étape 6 et entrez 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 vos abonnements e-mail ou SMS depuis Shopify (facultatif)

Si vous utilisez les canaux e-mail ou SMS, vous pouvez synchroniser vos états d’abonnement au marketing par e-mail et SMS depuis Shopify vers Braze.

• e-mail
• double abonnement sms

Si vous synchronisez les abonnements au marketing par e-mail depuis Shopify, Braze crée 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.

Remarque

Comme mentionné dans l’aperçu de Shopify, si vous souhaitez utiliser un formulaire de capture tiers, vos développeurs doivent intégrer le code du SDK Braze. Cela vous permettra de capturer l’adresse e-mail et le statut d’abonnement global aux e-mails à partir des soumissions de formulaires. Plus précisément, vous devez implémenter et tester ces méthodes dans votre fichier theme.liquid :

• setEmail : définit l’adresse e-mail sur le profil utilisateur
• setEmailNotificationSubscriptionType : met à jour le statut d’abonnement global aux e-mails

Utilisez le double abonnement SMS pour envoyer votre texte de confirmation personnalisé via Braze au lieu de l’e-mail de confirmation de Shopify. Pour activer le double abonnement SMS :

1. Dans l’interface d’administration Shopify, accédez à Settings > Notifications > Customer notifications.
2. Désactivez le double abonnement marketing pour les SMS.
3. Définissez le SMS au paiement sur abonnement simple.
4. Dans vos paramètres SMS de Braze, sélectionnez Use Braze SMS double opt-in.

Pour plus d’informations sur le double abonnement SMS de Braze et le flux d’abonnement des utilisateurs, consultez l’aperçu de Shopify.

Étape 7 : Synchroniser les produits (facultatif)

Vous pouvez synchroniser tous les produits de votre boutique Shopify vers un catalogue Braze pour une personnalisation plus poussée des messages. Les mises à jour automatiques se font quasiment en temps réel, de sorte que votre catalogue reflète toujours les derniers détails produit. Pour en savoir plus, consultez Synchronisation des produits Shopify.

Étape 8 : Activer les canaux

Pour activer les messages in-app, les Banners 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 messages in-app pour les cas d’usage de formulaires de capture de prospects, consultez In-App Messages.
• Banners : pour activer les Banners pour les cas d’usage de personnalisation de vitrine Shopify, consultez Banners.
• Feature Flags : pour activer les Feature Flags pour les cas d’usage d’expérimentation sur la vitrine Shopify, consultez Feature Flags.

Étape 9 : Terminer la configuration

Une fois toutes les étapes parcourues, 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 qui s’affiche.

Exemple de code

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