Skip to content

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 Ihrem Hydrogen-Storefront hinzufügen, verbinden Sie Ihren Shopify-Shop und starten Sie das benutzerdefinierte Setup-Onboarding. Falls Sie Ihren Shop noch nicht verbunden haben, schließen Sie Ihren Shopify-Shop verbinden ab, fahren Sie dann mit Braze SDKs aktivieren fort und wählen Sie Custom setup.

Im benutzerdefinierten Setup-Ablauf werden Sie von Braze aufgefordert, die Website-App für Ihren 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, da Braze diesen Namen für den Standard-Shopify-Integrationspfad 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 Kopieren für jeden Wert – Sie müssen 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. 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 eine Callback-URI für die Anmeldung hinzu. (Die URI wird automatisch hinzugefügt, wenn 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 während des benutzerdefinierten Setup-Onboardings 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:




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

Fügen Sie dann diese Einstellung als Schlüssel der obersten Ebene 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 kann sich diese Komponente entweder in der Datei root.jsx oder layout.jsx befinden:




// 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 Komponenten-Loader unter Verwendung 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: Shopify-Kontoanmeldungs-Event hinzufügen

Erfassen Sie, wann sich ein:e Käufer:in in ihr Konto einloggt und ihre Nutzerinformationen mit Braze synchronisiert werden. Dies umfasst den Aufruf unserer changeUser-Methode, um Kund:innen mit einer externen Braze-ID zu identifizieren.

Stellen Sie vor Beginn 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 jedes Mal 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 Komponenten-Loader 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 Tracking 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 aus der Fetcher-Action zurück, damit Braze auf seine Eigenschaften zugreifen kann. Navigieren 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 in der Regel 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 Fetcher-Zustand ändert (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 die Aktualisierung eines bestehenden 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>
  );
}

Braze-Shopify-Integration installieren

Schritt 1: Ihren Shopify-Shop verbinden

Gehen Sie zur Shopify-Partnerseite, um mit der Einrichtung zu beginnen. 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 den Installationsprozess 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 benutzerdefinierte Einrichtung beinhaltet eine Website-App-Auswahl. Wählen Sie die App aus, die Ihre Storefront betreibt, oder erstellen Sie eine neue, 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-Prozess fortfahren, stellen Sie sicher, 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 von Shopify-Webhooks unterstützt werden. Ausführliche Informationen zu den Daten, die über diese Integration getrackt werden, finden Sie unter Shopify-Daten-Features.

Einrichtungsschritt zum Tracken von Shopify-Daten.

Schritt 4: Historischer Backfill (optional)

Über die benutzerdefinierte Einrichtung können Sie optional denselben historischen Shopify-Datenimport einbeziehen wie bei der Standardintegration: Bestell-Events 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 Datenimport einzubeziehen, aktivieren Sie das Kontrollkästchen für die Option des anfänglichen Datenimports.

Wenn Sie den Backfill lieber später durchführen möchten, können Sie die anfängliche Einrichtung 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 im anfänglichen Import, das Umsatz-Reporting-Verhalten und die Überwachung der Synchronisierung finden Sie unter Historischer Backfill.

Schritt 5: Benutzerdefiniertes Daten-Tracking einrichten (fortgeschritten)

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 (fortgeschritten)
Angepasste Events Angepasste Attribute
  • Verwendung eines individuellen Rabattcodes
  • Interaktion mit einer personalisierten Produktempfehlung
  • Lieblingsmarken oder -produkte
  • Bevorzugte Shopping-Kategorien
  • 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 benutzerdefinierter Daten finden Sie unter User object und logCustomEvent.

Schritt 6: Konfigurieren, wie Sie Nutzer:innen verwalten (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 Ihre 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-Metafeld 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 Metafeld erstellt wurde, befüllen Sie es für Ihre Kund:innen. Wir empfehlen die folgenden Ansätze:

  • Auf Customer-Creation-Webhooks lauschen: Richten Sie einen Webhook ein, der auf customer/create-Events lauscht. Dies ermöglicht es Ihnen, das Metafeld zu schreiben, wenn ein:e neue:r Kund:in erstellt wird.
  • Bestehende Kund:innen nachträglich befüllen: Verwenden Sie die Admin API oder Customer API, um das Metafeld für zuvor erstellte Kund:innen nachträglich zu befü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-Metafeld 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 Storefront-Name 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. Ihre Endpunkt-Logik sollte Null-Werte hier berücksichtigen (zum Beispiel 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 die shopify_customer_id und die email_address (falls 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-Metafeld 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 externen Braze-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)

Sie haben die Möglichkeit, Ihre E-Mail- oder SMS-Marketing-Opt-ins von Shopify zu erfassen.

Wenn Sie die E-Mail- oder SMS-Kanäle nutzen, können Sie Ihre E-Mail- und SMS-Marketing-Opt-in-Status in Braze synchronisieren. Wenn Sie E-Mail-Marketing-Opt-ins von Shopify synchronisieren, erstellt Braze automatisch eine E-Mail-Abo-Gruppe für alle Nutzer:innen, die mit diesem bestimmten Shop verbunden sind. Sie müssen einen eindeutigen Namen für diese Abo-Gruppe erstellen.

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

Schritt 7: Produkte synchronisieren (optional)

Sie können alle Produkte aus Ihrem Shopify-Shop in einen Braze-Katalog synchronisieren, um eine tiefergehende Messaging-Personalisierung zu ermöglichen. Automatische Updates erfolgen nahezu in Echtzeit, 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, die für jeden Kanal bereitgestellt werden:

  • In-App Messages: Um In-App Messages für Anwendungsfälle mit Lead-Erfassungsformularen zu aktivieren, siehe In-App Messages.
  • Banner: Um Banner für Anwendungsfälle zur Personalisierung der Shopify-Storefront zu aktivieren, siehe Banner.
  • Feature-Flags: Um Feature-Flags für Experimentier-Anwendungsfälle auf der Shopify-Storefront zu aktivieren, siehe 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 dann das Braze-App-Embed auf Ihrer Shopify-Admin-Seite, wie durch das angezeigte 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-Hydrogen-App, die den gesamten Code aus den vorherigen Schritten enthält.

Documentation for the Braze customer engagement platform.

Resources
Legal
Company
© 2026 Braze, Inc. All rights reserved.
Braze-Status wird geprüft
New Stuff!