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: Website-App auswählen und SDK-Zugangsdaten kopieren

Bevor Sie Code zu Ihrer Hydrogen-Storefront hinzufügen, verbinden Sie Ihren Shopify-Shop und starten das Onboarding für die angepasste Einrichtung. Falls Sie Ihren Shop noch nicht verbunden haben, führen Sie zuerst die Schritte unter Shopify-Shop verbinden aus. Fahren Sie dann mit Braze SDKs aktivieren fort und wählen Sie Angepasste Einrichtung.

Im Ablauf der angepassten Einrichtung fordert Braze Sie auf, die Website-App für Ihre Headless-Storefront auszuwählen:

  1. Wählen Sie eine bestehende Website-App aus oder erstellen Sie eine neue. Sie können der App einen beliebigen Namen geben, außer Shopify. Dieser Name ist für den Standard-Integrationsweg von Shopify reserviert.
  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 für jeden Wert Kopieren. Sie müssen dafür nicht Einstellungen > App-Einstellungen ö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 Einstellungen > App-Einstellungen umbenennen. Solange die App mit Ihrer Shopify-Integration verbunden ist, können Sie sie nicht löschen.

Schritt 2: Subdomain und Umgebungsvariablen hinzufügen

  1. Richten Sie Ihre Shopify-Subdomain so ein, dass sie Traffic von Ihrem Online-Shop zu Hydrogen weiterleitet.
  2. Fügen Sie eine Callback-URI für die Anmeldung hinzu. (Die URI wird automatisch hinzugefügt, sobald die Domain hinzugefügt wird.)
  3. Richten Sie Ihre Shopify-Umgebungsvariablen ein:
    • Erstellen Sie zwei Umgebungsvariablen mit dem API-Schlüssel und dem SDK-Endpunkt, die Sie beim Onboarding der angepassten Einrichtung in Schritt 1 kopiert haben.
    • BRAZE_API_KEY
    • BRAZE_API_URL

Schritt 3: Onsite-Tracking aktivieren

Initialisieren Sie zunächst das Braze Web SDK. Wir empfehlen dafür die Installation unseres NPM-Pakets:




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 Datei vite.config.js ein:




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

Nach der Installation des NPM-Pakets müssen Sie das SDK innerhalb eines useEffect-Hooks in der Komponente Layout initialisieren. Je nach 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 Loader der Komponente mithilfe der in Schritt 2 erstellten Umgebungsvariablen eingebunden 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: Event für die Shopify-Kontoanmeldung hinzufügen

Tracken Sie, wann sich Käufer:innen in ihrem Konto anmelden, und synchronisieren Sie ihre Nutzerinformationen mit Braze. Dazu gehört der Aufruf unserer Methode changeUser, um Kund:innen mit einer externen Braze-ID zu identifizieren.

Stellen Sie vorab sicher, dass Sie die Callback-URIs eingerichtet haben, damit die Kundenanmeldung in Hydrogen funktioniert. Weitere Informationen finden Sie unter Using the Customer Account API with Hydrogen.

  1. Definieren Sie nach dem Einrichten der Callback-URIs eine Funktion, die das Braze SDK aufruft. Erstellen Sie eine neue Datei (zum Beispiel Tracking.jsx) und importieren Sie sie in Ihre 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 GraphQL-Abfrage der Customer API 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 die Events „Product Viewed“ und „Cart Updated“ hinzufügen

Events vom Typ „Product Viewed“

  1. Fügen Sie diese Funktion zu Ihrer Datei Tracking.jsx 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. Damit die obige Funktion jedes Mal aufgerufen wird, wenn Nutzer:innen eine Produktseite besuchen, fügen Sie der Komponente Product in der Datei app/routes/products.$handle.jsx einen useEffect-Hook 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 Loader der Komponente 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,
  };
}

Events vom Typ „Cart Updated“

  1. Definieren Sie Funktionen, um das Event cart_updated zu tracken und den Warenkorb-Token zu setzen:



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 Objekt cart aus der Fetcher-Aktion zurück, damit Braze auf seine Eigenschaften zugreifen kann. Öffnen Sie dazu Ihre Datei app/routes/cart.jsx und fügen Sie Folgendes zur Funktion action 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 in der Regel eine Komponente CartForm, die den Zustand des Warenkorb-Objekts verwaltet. Sie kommt zum Einsatz, wenn Artikel zum Warenkorb hinzugefügt, daraus entfernt oder in ihrer Menge geändert werden. Fügen Sie in der Komponente AddToCartButton einen weiteren useEffect-Hook hinzu, der die Funktion trackCartUpdated aufruft, sobald sich der Zustand des Formular-Fetchers ändert (also immer dann, wenn der Warenkorb der Nutzer:innen 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 ein vorhandenes Produkt in Ihrem Warenkorb aktualisieren. Fügen Sie Folgendes zu den Komponenten CartLineRemoveButton und CartLineUpdateButton hinzu (standardmäßig in der Datei app/components/CartLineItem.jsx):



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

Braze Shopify-Integration installieren

Schritt 1: Ihren Shopify-Shop verbinden

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

Einrichtungsseite der Shopify-Integration im Braze-Dashboard.

Schritt 2: Braze SDKs aktivieren

Wählen Sie für Shopify Hydrogen oder Headless-Shops die Option Custom setup aus.

Die angepasste Einrichtung enthält eine Auswahl für Website-Apps. Wählen oder erstellen Sie die App, auf der Ihre Storefront basiert, und kopieren Sie dann den API-Schlüssel und den SDK-Endpunkt, die im Onboarding-Schritt angezeigt werden. Weitere Informationen finden Sie unter Schritt 1: Website-App auswählen und SDK-Zugangsdaten kopieren.

Bevor Sie mit dem Onboarding fortfahren, vergewissern Sie sich, 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 um weitere Shopify-Events und -Attribute, die über Shopify-Webhooks bereitgestellt werden. Ausführliche Informationen zu den Daten, die über diese Integration getrackt werden, finden Sie unter Shopify-Daten-Features.

Einrichtungsschritt zum Tracking von Shopify-Daten.

Schritt 4: Historisches Backfill (optional)

Über die angepasste Einrichtung können Sie optional denselben historischen Shopify-Datenimport wie bei der Standardintegration einbeziehen.

Wählen Sie Turn on historical backfill aus und legen Sie dann einen Zeitraum für Bestellungen (Past 90 days, Past year oder Past 2 years) und für Kundenprofile (Past year, Past 2 years oder All time) fest. Diese Auswahl kann nach Abschluss der Einrichtung nicht mehr geändert werden.

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

Abschnitt zum historischen Daten-Backfill mit ausgewählter Option „Turn on historical backfill“ sowie Zeitraumauswahl für Bestellungen und Kundenprofile.

Die vollständige Liste der Daten im Erstimport, Informationen zum Verhalten der Umsatzberichte und zur Überwachung der Synchronisierung finden Sie unter Historisches Backfill.

Schritt 5: Tracking angepasster Daten einrichten (fortgeschritten)

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

Schritt 5: Tracking angepasster Daten einrichten (fortgeschritten)
Angepasste Events Angepasste Attribute
  • Verwendung 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 (also auf Aktivitäten warten), um Events oder angepasste Attribute zu protokollieren. Weitere Informationen zum Protokollieren angepasster Daten finden Sie unter User-Objekt und logCustomEvent.

Schritt 6: Verwaltung von Nutzer:innen konfigurieren (optional)

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

Abschnitt „Collect subscribers“.

Standardmäßig wandelt Braze E-Mail-Adressen aus Shopify automatisch in Kleinbuchstaben um, bevor sie als externe ID verwendet werden. Wenn Sie E-Mail-Adressen oder gehashte E-Mail-Adressen als externe ID verwenden, stellen Sie sicher, dass Ihre E-Mail-Adressen ebenfalls in Kleinbuchstaben umgewandelt werden, bevor Sie sie als externe ID zuweisen oder aus anderen Datenquellen hashen. So vermeiden Sie Abweichungen bei externen IDs und doppelte Nutzerprofile in Braze.

Schritt 6.1: Das Metafeld braze.external_id erstellen

  1. Gehen Sie auf Ihrer Shopify-Admin-Seite 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 Eintrag ID-Typ aus.

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

  • Webhooks für die Kundenerstellung abonnieren: Richten Sie einen Webhook ein, der auf customer/create-Events wartet. So können Sie das Metafeld schreiben, sobald neue Kund:innen angelegt werden.
  • Backfill für bestehende Kund:innen: Verwenden Sie die Admin API oder die Customer API, um das Metafeld für bereits angelegte Kund:innen nachträglich zu befüllen.

Schritt 6.2: Endpunkt zum Abrufen Ihrer externen ID erstellen

Sie müssen einen öffentlichen Endpunkt erstellen, den Braze aufrufen kann, um die externe ID abzurufen. So kann Braze die ID auch in Fällen abrufen, in denen Shopify das Metafeld braze.external_id nicht direkt bereitstellen kann.

Endpunkt-Spezifikationen

Methode: GET

Braze sendet die folgenden Parameter an Ihren Endpunkt:

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

Dieses Feld kann in bestimmten Webhook-Szenarien fehlen. Die Logik Ihres Endpunkts sollte hier Nullwerte berücksichtigen (rufen Sie beispielsweise die E-Mail-Adresse über die shopify_customer_id ab, 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 den Statuscode 200, der das JSON mit der externen ID zurückgibt:




{
  "external_id": "my_external_id"
}
Validierung

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

Fehlerverhalten und Zusammenführung

Jeder andere Statuscode als 200 gilt als Fehler.

  • 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 die angepasste externe ID als Typ Ihrer externen ID in Braze ausgewählt haben.

Überlegungen
  • 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 aus Shopify erfassen (optional)

Wenn Sie die E-Mail-, SMS- oder WhatsApp-Kanäle nutzen, können Sie Ihre E-Mail-, SMS- und WhatsApp-Marketing-Opt-in-Status von Shopify mit 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.

Wenn Sie WhatsApp-Nachrichten über Braze versenden, können Sie auch WhatsApp-Marketing-Opt-ins aus Shopify synchronisieren. Wählen Sie Collect WhatsApp subscribers aus und wählen Sie dann die WhatsApp-Abo-Gruppen aus, in die synchronisiert werden soll.

Das Kontrollkästchen „Collect WhatsApp subscribers“ mit einer ausgewählten WhatsApp-Abo-Gruppe und darunter die Tabelle „Route consent by region“.

Braze synchronisiert nur die WhatsApp-Einwilligung, die Shopify für eine:n Kund:in speichert. Ein SMS- oder E-Mail-Opt-in meldet Kund:innen nicht für WhatsApp an, und für WhatsApp gibt es kein Double-Opt-in. Weitere Informationen finden Sie unter WhatsApp-Marketing-Opt-ins.

Schritt 7: Produkte synchronisieren (optional)

Sie können alle Produkte aus Ihrem Shopify-Shop mit einem Braze-Katalog synchronisieren, um Ihre Nachrichten noch stärker zu personalisieren. Updates erfolgen automatisch nahezu in Realtime, sodass Ihr Katalog stets die aktuellen Produktdetails widerspiegelt. Weitere Informationen finden Sie unter Shopify-Produktsynchronisierung.

Einrichtungsschritt zum Synchronisieren von Produktdaten mit Braze.

Schritt 8: Kanäle aktivieren

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

  • In-App-Nachrichten: Informationen zum Aktivieren von In-App-Nachrichten für Anwendungsfälle mit Formularen zur Lead-Erfassung finden Sie unter In-App-Nachrichten.
  • Banner: Informationen zum Aktivieren von Bannern für Anwendungsfälle zur Personalisierung Ihrer Shopify-Storefront finden Sie unter Banner.
  • Feature-Flags: Informationen zum Aktivieren von Feature-Flags für Experimente in Ihrer Shopify-Storefront finden Sie unter Feature-Flags.

Schritt 9: Einrichtung abschließen

Nachdem Sie alle Schritte durchlaufen haben, wählen Sie Finish Setup aus, um zur Partnerseite zurückzukehren. Aktivieren Sie anschließend das Braze App-Embed auf Ihrer Shopify-Admin-Seite, wie im angezeigten Banner angegeben.

Banner mit dem Hinweis, das Braze App-Embed in Shopify zu aktivieren, um die Einrichtung Ihrer Integration abzuschließen.

Beispielcode

shopify-hydrogen-example ist eine Beispiel-App für Hydrogen, 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!