Zum Inhalt springen

Shopify angepasste Integration einrichten

Auf dieser Seite erfahren Sie, wie Sie Braze mit einem Shopify Hydrogen Shop oder einem beliebigen Headless-Shopify-Shop integrieren können, indem Sie eine angepasste Storefront verwenden.

Dieser Leitfaden verwendet das Hydrogen-Framework von Shopify als Beispiel. Sie können jedoch einen ähnlichen Ansatz verfolgen, wenn Ihre Marke Shopify für das Backend Ihres Shops mit einem „Headless“-Front-End-Setup verwendet.

Um Ihren Shopify Headless Shop mit Braze zu integrieren, müssen Sie diese beiden Ziele erreichen:

  1. Initialisieren und laden Sie das Braze Web SDK, um das Onsite-Tracking zu ermöglichen

    Fügen Sie manuell Code in Ihre Shopify-Website ein, um das Braze Onsite-Tracking zu aktivieren. Durch die Implementierung des Braze SDK in Ihrem Shopify Headless Shop können Sie Onsite-Aktivitäten nachverfolgen, einschließlich Sitzungen, anonymes Nutzer:innenverhalten, Aktionen vor dem Checkout und alle angepassten Events oder angepassten Attribute, die Sie zusammen mit Ihrem Entwicklungsteam einbeziehen möchten. Sie können auch alle Kanäle hinzufügen, die von den SDKs unterstützt werden, wie In-App-Nachrichten oder Content Cards.
  1. Installieren Sie die Braze Shopify-Integration

    Nachdem Sie Ihren Shopify-Shop mit Braze verbunden haben, erhalten Sie über Shopify-Webhooks Zugriff auf Kundendaten, Checkout-, Bestell- und Produktdaten.

Um diese Ziele zu erreichen, gehen Sie folgendermaßen vor:

Braze Web SDK initialisieren und laden

Schritt 1: Eine Website-App auswählen und SDK-Zugangsdaten kopieren

Bevor Sie Code zu Ihrem Hydrogen-Storefront hinzufügen, verbinden Sie Ihren Shopify-Shop und starten Sie das Onboarding für die angepasste Einrichtung. Falls Sie Ihren Shop noch nicht verbunden haben, schließen Sie Ihren Shopify-Shop verbinden ab und fahren Sie dann mit Braze SDKs aktivieren fort. Wählen Sie Custom setup aus.

Im Ablauf der angepassten Einrichtung werden Sie von Braze aufgefordert, die Website-App für Ihren Headless-Storefront auszuwählen:

  1. Wählen Sie eine vorhandene Website-App aus oder erstellen Sie eine neue. Sie können die App beliebig benennen, außer Shopify, da dieser Name von Braze für den Standard-Shopify-Integrationspfad reserviert ist.
  2. Braze zeigt den API-Schlüssel und die Basis-URL (Ihren SDK-Endpunkt) der ausgewählten App im Onboarding-Schritt an. Wählen Sie Copy für jeden Wert aus – Sie müssen Settings > App Settings nicht öffnen.
  3. Verwenden Sie den kopierten API-Schlüssel als BRAZE_API_KEY und den SDK-Endpunkt als BRAZE_API_URL in Ihren Shopify-Umgebungsvariablen (Schritt 2).

Nachdem Sie den Shop verbunden haben, können Sie die ausgewählte Website-App unter Settings > App Settings umbenennen. Sie können die App nicht löschen, solange sie mit Ihrer Shopify-Integration verbunden ist.

Schritt 2: Subdomain und Umgebungsvariablen hinzufügen

  1. Richten Sie Ihre Shopify-Subdomain ein, um den Traffic von Ihrem Online-Shop zu Hydrogen umzuleiten.
  2. Fügen Sie einen Callback-URI für die Anmeldung hinzu. (Der URI wird automatisch hinzugefügt, wenn die Domain ergänzt wird.)
  3. Richten Sie Ihre Shopify-Umgebungsvariablen ein:
    • Erstellen Sie zwei Umgebungsvariablen mit dem API-Schlüssel und dem SDK-Endpunkt, die Sie während des Onboardings der angepassten Einrichtung in Schritt 1 kopiert haben.
    • BRAZE_API_KEY
    • BRAZE_API_URL

Schritt 3: Onsite-Tracking aktivieren

Der erste Schritt besteht darin, das Braze Web SDK zu initialisieren. Wir empfehlen, dies durch die Installation unseres NPM-Pakets zu tun:




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

Fügen Sie dann diese Einstellung als Top-Level-Schlüssel in Ihre vite.config.js-Datei ein:




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

Nach der Installation des NPM-Pakets müssen Sie das SDK innerhalb eines useEffect-Hooks in der Layout-Komponente initialisieren. Je nach Ihrer Hydrogen-Version befindet sich diese Komponente entweder in der Datei root.jsx oder layout.jsx:




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

Die Werte data.brazeApiKey und data.brazeApiUrl müssen im Komponentenloader unter Verwendung der in Schritt 2 erstellten Umgebungsvariablen bereitgestellt werden:




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,
    },
  };
}

Schritt 4: Ein Shopify-Account-Login-Event hinzufügen

Verfolgen Sie, wann sich ein:e Käufer:in in sein/ihr Konto einloggt und die Nutzerinfos mit Braze synchronisiert. Dazu gehört der Aufruf unserer changeUser-Methode, um Kund:innen mit einer externen Braze-ID zu identifizieren.

Stellen Sie vor dem Start sicher, dass Sie die Callback-URIs für die Kundenanmeldung in Hydrogen eingerichtet haben. Weitere Informationen finden Sie unter Using the Customer Account API with Hydrogen.

  1. Nachdem Sie die Callback-URIs eingerichtet haben, definieren Sie eine Funktion zum Aufrufen des Braze SDK. Erstellen Sie eine neue Datei (z. B. Tracking.jsx) und importieren Sie sie aus Ihren Komponenten:



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. Fügen Sie im selben useEffect-Hook, der das Braze SDK initialisiert, den Aufruf dieser Funktion hinzu:



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. Rufen Sie die E-Mail-Adresse und Telefonnummer der Kund:innen in Ihrer Customer-API-GraphQL-Abfrage ab, die sich in der Datei app/graphql/customer-account/CustomerDetailsQuery.js befindet:



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. Laden Sie abschließend die Kundendaten in Ihrer Loader-Funktion:



// 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,
    },
  };
}

Schritt 5: Tracking für „Product Viewed“- und „Cart Updated“-Events hinzufügen

„Product Viewed“-Events

  1. Fügen Sie diese Funktion zu Ihrer Tracking.jsx-Datei hinzu:



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. Um die vorherige Funktion aufzurufen, wenn Nutzer:innen eine Produktseite besuchen, fügen Sie einen useEffect-Hook zur Product-Komponente in der Datei app/routes/products.$handle.jsx hinzu:



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. Fügen Sie den Wert für storefrontUrl hinzu (da er standardmäßig nicht im Komponentenloader enthalten ist):



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,
  };
}

„Cart Updated“-Events

  1. Definieren Sie Funktionen zum Tracken des cart_updated-Events und zum Setzen des Warenkorb-Tokens:



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. Geben Sie das cart-Objekt von der Fetcher-Action zurück, damit Braze auf dessen Eigenschaften zugreifen kann. Gehen Sie dazu zu Ihrer Datei app/routes/cart.jsx und fügen Sie Folgendes zur action-Funktion hinzu:



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

Weitere Informationen zu Remix-Fetchern finden Sie unter useFetcher.

  1. Hydrogen-Shops definieren normalerweise eine CartForm-Komponente, die den Zustand des Warenkorb-Objekts verwaltet. Diese wird beim Hinzufügen, Entfernen und Ändern der Menge von Artikeln im Warenkorb verwendet. Fügen Sie einen weiteren useEffect-Hook in der AddToCartButton-Komponente hinzu, der die trackCartUpdated-Funktion aufruft, wenn sich der Zustand des Formular-Fetchers ändert (also wenn der Warenkorb aktualisiert wird):



// 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. Verwenden Sie denselben fetcherKey für die Aktionen, die für das Aktualisieren eines vorhandenen Produkts aus Ihrem Warenkorb verantwortlich sind. Fügen Sie Folgendes zu den Komponenten CartLineRemoveButton und CartLineUpdateButton hinzu (standardmäßig in der Datei app/components/CartLineItem.jsx zu finden):



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

Installation der Braze-Shopify-Integration

Schritt 1: Shopify-Shop verbinden

Gehen Sie zur Shopify-Partnerseite, um die Einrichtung zu starten. Wählen Sie zunächst Begin Setup, um die Braze-Anwendung aus dem Shopify App Store zu installieren. Folgen Sie den geführten Schritten, um den Installationsprozess abzuschließen.

Seite zur Einrichtung der Shopify-Integration im Braze-Dashboard.

Schritt 2: Braze SDKs aktivieren

Für Shopify Hydrogen oder Headless-Shops wählen Sie die Option Custom setup.

Das benutzerdefinierte Setup enthält eine Website-App-Auswahl. Wählen oder erstellen Sie die App, die Ihren Storefront unterstützt, und kopieren Sie dann den API-Schlüssel und den SDK-Endpunkt, die im Onboarding-Schritt angezeigt werden. Weitere Details finden Sie unter Schritt 1: Website-App auswählen und SDK-Zugangsdaten kopieren.

Bevor Sie mit dem Onboarding fortfahren, bestätigen Sie, dass Sie das Braze SDK mit diesen Zugangsdaten zu Ihrer Shopify-Website hinzugefügt haben.

Einrichtungsschritt zum Aktivieren der Braze SDKs.

Schritt 3: Shopify-Daten tracken

Erweitern Sie Ihre Integration, indem Sie weitere Shopify-Events und -Attribute hinzufügen, die über Shopify-Webhooks bereitgestellt werden. Ausführliche Informationen zu den über diese Integration getrackten Daten finden Sie unter Shopify-Daten-Features.

Einrichtungsschritt zum Tracken von Shopify-Daten.

Schritt 4: Historischer Backfill (optional)

Über das benutzerdefinierte Setup können Sie optional denselben historischen Shopify-Datenladevorgang wie bei der Standard-Integration einbeziehen: Bestellereignisse der letzten 90 Tage und Nutzerprofile des letzten Jahres, jeweils zurückgerechnet ab dem Datum, an dem Sie Ihre Integration abschließen. Um diesen anfänglichen Datenladevorgang einzubeziehen, aktivieren Sie das Kontrollkästchen für die Option zum anfänglichen Datenladevorgang.

Wenn Sie den Backfill lieber zu einem späteren Zeitpunkt durchführen möchten, können Sie die Ersteinrichtung jetzt abschließen und zu einem späteren Zeitpunkt zu diesem Schritt zurückkehren.

Abschnitt zur Einrichtung des historischen Daten-Backfills.

Die vollständige Liste der Daten beim anfänglichen Ladevorgang, das Verhalten der Umsatzberichte und die Überwachung der Synchronisierung finden Sie unter Historischer Backfill.

Schritt 5: Benutzerdefiniertes Daten-Tracking einrichten (erweitert)

Mit den Braze SDKs können Sie angepasste Events oder angepasste Attribute tracken, die über die unterstützten Daten dieser Integration hinausgehen. Angepasste Events erfassen einzigartige Interaktionen in Ihrem Shop, wie zum Beispiel:

Schritt 5: Benutzerdefiniertes Daten-Tracking einrichten (erweitert)
Angepasste Events Angepasste Attribute
  • Verwenden eines angepassten Rabattcodes
  • Interaktion mit einer personalisierten Produktempfehlung
  • Lieblingsmarken oder -produkte
  • Bevorzugte Einkaufskategorien
  • Mitgliedschafts- oder Treuestatus

Das SDK muss auf dem Gerät der Nutzer:innen initialisiert sein (auf Aktivität lauschen), um Events oder angepasste Attribute zu protokollieren. Weitere Informationen zum Protokollieren angepasster Daten finden Sie unter User object und logCustomEvent.

Schritt 6: Nutzerverwaltung konfigurieren (optional)

Wählen Sie Ihren external_id-Typ aus dem Dropdown aus.

Abschnitt „Abonnent:innen erfassen“.

Standardmäßig konvertiert Braze E-Mails von Shopify automatisch in Kleinbuchstaben, bevor sie als externe ID verwendet werden. Wenn Sie E-Mail oder gehashte E-Mail als externe ID verwenden, stellen Sie sicher, dass Ihre E-Mail-Adressen ebenfalls in Kleinbuchstaben konvertiert werden, bevor Sie sie als externe ID zuweisen oder bevor Sie sie aus anderen Datenquellen hashen. Dies hilft, Diskrepanzen bei externen IDs zu vermeiden und die Erstellung doppelter Nutzerprofile in Braze zu verhindern.

Schritt 6.1: Das braze.external_id-Metafield erstellen

  1. Gehen Sie in Ihrem Shopify-Admin-Panel zu Einstellungen > Metafelder.
  2. Wählen Sie Kund:innen > Definition hinzufügen aus.
  3. Geben Sie unter Namespace und Schlüssel den Wert braze.external_id ein.
  4. Wählen Sie unter Typ den ID-Typ aus.

Nachdem das Metafield erstellt wurde, füllen Sie es für Ihre Kund:innen. Wir empfehlen die folgenden Ansätze:

  • Auf Webhooks zur Kundenerstellung lauschen: Richten Sie einen Webhook ein, der auf customer/create-Events lauscht. Damit können Sie das Metafield schreiben, wenn ein:e neue:r Kund:in erstellt wird.
  • Bestehende Kund:innen nachfüllen: Verwenden Sie die Admin API oder Customer API, um das Metafield für zuvor erstellte Kund:innen nachzufüllen.

Schritt 6.2: Einen Endpunkt zum Abrufen Ihrer externen ID erstellen

Sie müssen einen öffentlichen Endpunkt erstellen, den Braze aufrufen kann, um die externe ID abzurufen. Dies ermöglicht es Braze, die ID in Szenarien abzurufen, in denen Shopify das braze.external_id-Metafield nicht direkt bereitstellen kann.

Endpunkt-Spezifikationen

Methode: GET

Braze sendet die folgenden Parameter an Ihren Endpunkt:

Parameter Obligatorisch Datentyp Beschreibung
shopify_customer_id Ja String Die Shopify-Kunden-ID.
shopify_storefront Ja String Der Storefront-Name für die Anfrage. Bsp.: <storefront_name>.myshopify.com
email_address Nein String Die E-Mail-Adresse der angemeldeten Nutzer:innen.

Dieses Feld kann in bestimmten Webhook-Szenarien fehlen. Ihre Endpunkt-Logik sollte Null-Werte hier berücksichtigen (z. B. die E-Mail über die shopify_customer_id abrufen, wenn Ihre interne Logik dies erfordert).
Beispiel-Endpunkt



GET https://mystore.com/custom_id?shopify_customer_id=1234&[email protected]&shopify_storefront=dev-store.myshopify.com
Erwartete Antwort

Braze erwartet einen 200-Statuscode mit der externen ID als JSON:




{
  "external_id": "my_external_id"
}
Validierung

Es ist entscheidend, zu validieren, dass shopify_customer_id und email_address (sofern vorhanden) mit den Kundenwerten in Shopify übereinstimmen. Sie können die Shopify Admin API oder Customer API verwenden, um diese Parameter zu validieren und das korrekte braze.external_id-Metafield abzurufen.

Fehlerverhalten und Zusammenführung

Jeder Statuscode außer 200 wird als Fehler betrachtet.

  • Auswirkungen auf die Zusammenführung: Wenn der Endpunkt fehlschlägt (nicht 200 zurückgibt oder ein Timeout auftritt), kann Braze die externe ID nicht abrufen. Folglich findet die Zusammenführung zwischen dem Shopify-Nutzer und dem Braze-Kundenprofil zu diesem Zeitpunkt nicht statt.
  • Wiederholungslogik: Braze kann standardmäßige sofortige Netzwerk-Wiederholungsversuche unternehmen. Wenn der Fehler jedoch bestehen bleibt, wird die Zusammenführung bis zum nächsten qualifizierenden Ereignis aufgeschoben (zum Beispiel, wenn Nutzer:innen das nächste Mal ihr Profil aktualisieren oder einen Checkout abschließen).
  • Unterstützbarkeit: Um eine zeitnahe Zusammenführung von Nutzer:innen zu gewährleisten, stellen Sie sicher, dass Ihr Endpunkt hochverfügbar ist und das optionale Feld email_address ordnungsgemäß verarbeitet.

Schritt 6.3: Ihre externe ID eingeben

Wiederholen Sie Schritt 6 und geben Sie Ihre Endpunkt-URL ein, nachdem Sie den benutzerdefinierten externen ID-Typ als Ihren Braze-externen-ID-Typ ausgewählt haben.

Hinweise
  • Wenn Ihre externe ID noch nicht generiert wurde, wenn Braze eine Anfrage an Ihren Endpunkt sendet, verwendet die Integration standardmäßig die Shopify-Kund:innen-ID, wenn die Funktion changeUser aufgerufen wird. Dieser Schritt ist entscheidend für das Zusammenführen des anonymen Nutzerprofils mit dem identifizierten Kundenprofil. Daher kann es vorübergehend vorkommen, dass verschiedene Arten von externen IDs in Ihrem Workspace existieren.
  • Wenn die externe ID im Metafeld braze.external_id verfügbar ist, priorisiert die Integration diese externe ID und weist sie zu.
    • Wenn die Shopify-Kund:innen-ID zuvor als externe Braze-ID festgelegt wurde, wird sie durch den Wert des Metafelds braze.external_id ersetzt.

Schritt 6.4: E-Mail- oder SMS-Opt-ins von Shopify erfassen (optional)

Wenn Sie die E-Mail- oder SMS-Kanäle nutzen, können Sie Ihre E-Mail- und SMS-Marketing-Opt-in-Status von Shopify in Braze synchronisieren.

Abschnitt „Abonnent:innen erfassen“ mit der Option, E-Mail- oder SMS-Marketing-Opt-ins zu erfassen.

Verwenden Sie das SMS-Double-Opt-in, um Ihren markenspezifischen Bestätigungstext über Braze statt über die Bestätigungs-E-Mail von Shopify zu senden. So aktivieren Sie das SMS-Double-Opt-in:

  1. Gehen Sie in der Shopify-Verwaltung zu Settings > Notifications > Customer notifications.
  2. Deaktivieren Sie das Marketing-Double-Opt-in für SMS.
  3. Stellen Sie die Checkout-SMS auf Single-Opt-in um.
  4. Wählen Sie in Ihren Braze-SMS-Einstellungen Use Braze SMS double opt-in aus.

Das Kontrollkästchen „Use Braze SMS double opt-in“, eine Warnung, zuerst das Shopify-SMS-Double-Opt-in zu deaktivieren, und das Bestätigungs-Kontrollkästchen.

Weitere Informationen zum Braze-SMS-Double-Opt-in und zum Abonnent:innen-Flow finden Sie unter Shopify-Übersicht.

Schritt 7: Produkte synchronisieren (optional)

Sie können alle Produkte aus Ihrem Shopify-Shop mit einem Braze-Katalog synchronisieren, um die Messaging-Personalisierung zu vertiefen. Automatische Updates erfolgen nahezu in Realtime, sodass Ihr Katalog immer die neuesten Produktdetails widerspiegelt. Weitere Informationen finden Sie unter Shopify-Produktsynchronisierung.

Einrichtungsschritt zur Synchronisierung von Produktdaten mit Braze.

Schritt 8: Kanäle aktivieren

Um In-App Messages, Banner und Feature-Flags über die direkte Shopify-Integration zu aktivieren, fügen Sie jeden Kanal zu Ihrem SDK hinzu. Folgen Sie den Dokumentationslinks für jeden Kanal:

  • In-App Messages: Um In-App Messages für Lead-Capture-Formular-Anwendungsfälle zu aktivieren, siehe In-App Messages.
  • Banner: Um Banner für Shopify-Storefront-Personalisierungs-Anwendungsfälle zu aktivieren, siehe Banner.
  • Feature-Flags: Um Feature-Flags für Shopify-Storefront-Experimentierungs-Anwendungsfälle zu aktivieren, siehe Feature-Flags.

Schritt 9: Einrichtung abschließen

Nachdem Sie alle Schritte durchlaufen haben, wählen Sie Finish Setup, um zur Partnerseite zurückzukehren. Aktivieren Sie dann das Braze-App-Embed in Ihrer Shopify-Administrationsseite, wie durch den angezeigten Banner angezeigt.

Banner, der besagt, dass Sie das Braze-App-Embed in Shopify aktivieren sollen, um die Einrichtung Ihrer Integration abzuschließen.

Beispielcode

shopify-hydrogen-example ist eine Beispiel-Hydrogen-App, die den gesamten Code aus den vorherigen Schritten enthält.

Dokumentation für die Braze-Kundenengagement-Plattform.

Ressourcen
Rechtliches
Unternehmen
© 2026 Braze, Inc. Alle Rechte vorbehalten.
Braze-Status wird geprüft
New Stuff!