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électionnez une application de site web et copiez les identifiants du SDK

Avant d’ajouter du code à votre vitrine Hydrogen, connectez votre boutique Shopify et lancez l’onboarding de configuration personnalisée. Si vous n’avez pas encore connecté votre boutique, suivez les étapes de Connecter votre boutique Shopify, puis passez à Activer les SDK de Braze et sélectionnez Configuration personnalisée.

Pendant la configuration personnalisée, Braze vous invite à sélectionner l’application de site web associée à votre vitrine headless :

1. Sélectionnez une application de site web existante ou créez-en une nouvelle. Vous pouvez lui donner n’importe quel nom, sauf Shopify, que Braze réserve à l’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 Copier pour chaque valeur : inutile d’ouvrir Paramètres > Paramètres de l’application.
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).

Une fois la boutique connectée, vous pouvez renommer l’application de site web sélectionnée dans Paramètres > Paramètres de l’application. 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 de site web sélectionnée pendant 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 peuvent ne pas fonctionner comme prévu.

Étape 2 : Ajoutez 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 une URI de rappel pour la connexion. (L’URI est ajoutée automatiquement lorsque vous ajoutez le domaine.)
3. Configurez vos variables d’environnement Shopify :
   • Créez deux variables d’environnement à partir de la clé API et de l’endpoint SDK copiés pendant l’onboarding de configuration personnalisée à l’Étape 1.
   • BRAZE_API_KEY
   • BRAZE_API_URL

Étape 3 : Activez le suivi sur site

La première étape consiste à initialiser le SDK Web de Braze. Nous vous 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 vitrines headless), vous recevez des notifications lorsque de nouvelles versions du SDK sont disponibles, mais c’est à vous de gérer les mises à jour en modifiant à la fois le code de votre vitrine et la version du SDK dans les paramètres d’intégration.

Ensuite, ajoutez 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 d’Hydrogen, ce composant se trouve 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 à l’aide des 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 définies dans le fichier Hydrogen entry.server.jsx) peuvent affecter le fonctionnement des scripts Braze, aussi bien en local qu’en production. Nous vous conseillons de tester via des builds de prévisualisation envoyés à Shopify par Oxygen ou via des déploiements personnalisés. En cas de problème, vous devrez configurer votre CSP pour autoriser l’exécution de notre JavaScript.

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

Suivez le moment où un client se connecte à son compte et synchronisez ses informations utilisateur avec Braze. Cela implique d’appeler notre méthode changeUser pour identifier les clients à l’aide d’un ID externe Braze.

Remarque

Nous ne proposons pas encore de recommandations pour prendre en charge un ID externe Braze personnalisé. Si vous en avez besoin dès maintenant pour votre intégration, 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 dans Hydrogen. Pour plus d’informations, consultez Utiliser l’API Customer Account avec Hydrogen.

1. Une fois les URI de rappel configurées, définissez une fonction qui appelle le SDK de Braze. Créez un nouveau fichier (par exemple 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 hook useEffect qui initialise le SDK de 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 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 : Ajoutez le suivi des événements Produit consulté et Panier mis à jour

Événements Produit consulté

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 cette fonction chaque fois qu’un utilisateur consulte 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 de « storefrontUrl » (elle n’est pas présente par défaut dans le loader du composant) :

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 Panier mis à jour

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 les fonctions qui suivent l’événement cart_updated et définissent le jeton du 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. Renvoyez l’objet cart depuis l’action du fetcher pour que Braze puisse accéder à ses propriétés : ouvrez votre fichier app/routes/cart.jsx et ajoutez 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é des articles d’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 (c’est-à-dire 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 la même fetcherKey pour les actions qui mettent à jour un produit déjà présent 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

Rendez-vous sur la page partenaire Shopify pour lancer la configuration. Sélectionnez d’abord Commencer la configuration pour installer l’application Braze depuis la boutique d’applications Shopify. Suivez ensuite les étapes guidées pour terminer l’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 de site web. Sélectionnez ou créez l’application qui alimente votre vitrine, puis copiez la clé API et l’endpoint SDK affichés à l’étape d’onboarding. Pour plus de détails, consultez Étape 1 : Sélectionner une application de site web et copier les identifiants SDK.

Avant de poursuivre l’onboarding, vérifiez que vous avez bien ajouté le SDK de Braze à votre site Shopify à l’aide de ces identifiants.

Étape 3 : Suivre les données Shopify

Enrichissez votre intégration en ajoutant d’autres événements et attributs Shopify, alimentés par les webhooks Shopify. Pour en savoir plus sur les données suivies via cette intégration, consultez Fonctionnalités de données Shopify.

Étape 4 : Remplissage historique (facultatif)

Avec la configuration personnalisée, vous pouvez inclure le même chargement de données Shopify historiques que dans l’intégration standard.

Sélectionnez Activer le remplissage historique, puis choisissez une plage de dates pour les commandes (90 derniers jours, Année dernière ou 2 dernières années) et pour les profils clients (Année dernière, 2 dernières années ou Toute la période). Ces sélections ne peuvent plus être modifiées une fois la configuration terminée.

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

Pour la liste complète des données incluses dans le chargement initial, le comportement des rapports de chiffre d’affaires et le suivi de la synchronisation, consultez Remplissage historique.

Étape 5 : Configuration du suivi des 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 spécifiques dans votre boutique, par exemple :

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 des données personnalisées, consultez Objet utilisateur et logCustomEvent.

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

Sélectionnez votre type d’external_id dans la liste déroulante.

Important

Utiliser une adresse e-mail ou une adresse e-mail hachée comme ID externe Braze peut simplifier la gestion des identités entre vos sources de données. Il est toutefois important de tenir compte des risques potentiels pour la confidentialité des utilisateurs et la sécurité des données.

• Informations faciles à deviner : Les adresses e-mail sont faciles à deviner, 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 accéder à des messages sensibles ou à des informations de compte.

Par défaut, Braze convertit automatiquement en minuscules les e-mails provenant de Shopify 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. Vous évitez ainsi les incohérences entre ID externes et la création de profils utilisateurs en double dans Braze.

Remarque

Les étapes suivantes dépendent de l’ID externe sélectionné :

• Si vous avez sélectionné un type d’ID externe personnalisé : Suivez 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é : Ignorez les étapes 6.1 à 6.3 et passez directement à l’étape 6.4.

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

1. Sur votre page d’administration Shopify, accédez à Paramètres > Métachamps.
2. Sélectionnez Clients > Ajouter une définition.
3. Pour Espace de nommage et clé, saisissez braze.external_id.
4. Pour Type, sélectionnez Type d’ID.

Une fois le champ méta 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. Vous pourrez ainsi renseigner le champ méta dès la création d’un nouveau client.
• Remplir les données des clients existants : Utilisez l’API Admin ou l’API Customer pour renseigner le champ méta 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. Braze peut ainsi obtenir l’ID lorsque Shopify ne peut pas fournir directement le champ méta 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 vérifier que shopify_customer_id et email_address (le cas échéant) correspondent aux valeurs client dans Shopify. Vous pouvez utiliser l’API Admin de Shopify ou l’API Customer pour valider ces paramètres et récupérer le bon champ méta 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 et saisissez l’URL de votre endpoint après avoir sélectionné l’ID externe personnalisé comme type d’ID externe Braze.

Points à prendre en compte

• 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, SMS ou WhatsApp, vous pouvez synchroniser vos états d’abonnement au marketing par e-mail, SMS et WhatsApp depuis Shopify vers Braze.

• e-mail
• double abonnement sms
• whatsapp

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. Vous devez donner un nom unique à 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 SMS de confirmation à l’image de votre marque via Braze, plutôt que 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. Configurez la collecte SMS lors du paiement en abonnement simple.
4. Dans vos paramètres SMS de Braze, sélectionnez Use Braze SMS double opt-in.

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

Si vous envoyez des messages WhatsApp via Braze, vous pouvez également synchroniser les abonnements au marketing WhatsApp depuis Shopify. Sélectionnez Collect WhatsApp subscribers, puis choisissez les groupes d’abonnement WhatsApp à synchroniser.

Important

Votre espace de travail doit disposer d’un compte WhatsApp Business connecté pour avoir des groupes d’abonnement WhatsApp. Vous pouvez en connecter un dans Partenaires technologiques > WhatsApp.

Braze synchronise uniquement le consentement WhatsApp que Shopify enregistre pour un client. Un abonnement par SMS ou par e-mail n’abonne pas un client à WhatsApp, et il n’existe pas de double abonnement pour WhatsApp. Pour en savoir plus, consultez la section Abonnements au marketing WhatsApp.

Étape 7 : Synchroniser les produits (facultatif)

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

Étape 8 : Activer les canaux

Pour activer les messages in-app, les bannières et les feature flags avec l’intégration directe Shopify, ajoutez chaque canal à votre SDK. Suivez les liens vers la documentation de chaque canal :

• Messages in-app : Pour activer les messages in-app dans des cas d’usage de formulaires de capture de prospects, consultez Messages in-app.
• Bannières : Pour activer les bannières dans des cas d’usage de personnalisation de la vitrine Shopify, consultez Bannières.
• Feature flags : Pour activer les feature flags dans des cas d’usage d’expérimentation sur la vitrine Shopify, consultez Feature flags.

Étape 9 : Terminer la configuration

Une fois toutes les étapes effectuées, sélectionnez Terminer la configuration pour revenir à la page partenaire. Activez ensuite l’intégration de l’application Braze dans la page d’administration Shopify, comme l’indique la bannière qui s’affiche.

Exemple de code

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