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 Ihrer Hydrogen-Storefront hinzufügen, verbinden Sie Ihren Shopify-Shop und starten Sie das benutzerdefinierte Setup-Onboarding. Falls Sie Ihren Shop noch nicht verbunden haben, führen Sie zunächst Ihren Shopify-Shop verbinden durch, fahren Sie dann mit Braze SDKs aktivieren fort und wählen Sie Custom setup.

Im benutzerdefinierten Setup-Flow 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 die App beliebig benennen, außer Shopify – diesen Namen reserviert Braze für den Standard-Shopify-Integrationspfad.
  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 Traffic von Ihrem Onlineshop zu Hydrogen umzuleiten.
  2. Fügen Sie einen Callback-URI für die Anmeldung hinzu. (Der 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 dazu die Installation unseres NPM-Pakets:

1
2
3

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

Dann fügen Sie diese Einstellung als Top-Level-Schlüssel in Ihrer vite.config.js-Datei hinzu:

1
2
3

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 Hydrogen-Version befindet sich diese Komponente entweder in der Datei root.jsx oder 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 (...);
}

Die Werte data.brazeApiKey und data.brazeApiUrl müssen im Komponenten-Loader unter Verwendung der in Schritt 2 erstellten Umgebungsvariablen enthalten sein:

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

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

Verfolgen Sie, wann sich eine Käuferin oder ein Käufer in ihr bzw. sein Konto einloggt und die Nutzerinformationen mit Braze synchronisiert werden. 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 eingerichtet haben, damit sie innerhalb von Hydrogen funktionieren. 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:
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);
  }
}
  1. Fügen Sie im selben useEffect-Hook, der das Braze SDK initialisiert, den Aufruf dieser Funktion hinzu:
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])
  1. Rufen Sie die E-Mail-Adresse und Telefonnummer der Kund:in in Ihrer Customer-API-GraphQL-Abfrage ab, die sich in der Datei app/graphql/customer-account/CustomerDetailsQuery.js befindet:
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
  }
`;
  1. Laden Sie abschließend die Kundendaten in Ihrer Loader-Funktion:
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,
    },
  };
}

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:
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
  )
}
  1. Um die obige Funktion aufzurufen, sobald eine Nutzerin oder ein Nutzer eine Produktseite besucht, fügen Sie einen useEffect-Hook zur Product-Komponente in der Datei app/routes/products.$handle.jsx hinzu:
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 (...)
}
  1. Fügen Sie den Wert für „storefrontUrl“ hinzu (da er standardmäßig nicht im Komponenten-Loader enthalten ist):
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,
  };
}

„Cart Updated“-Events

  1. Definieren Sie Funktionen zum Tracking des cart_updated-Events und zum Setzen des Warenkorb-Tokens:
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);
    }
  }
}
  1. Geben Sie das cart-Objekt aus der Fetcher-Aktion zurück, damit Braze auf dessen Eigenschaften zugreifen kann. Navigieren Sie dazu zu Ihrer Datei app/routes/cart.jsx und fügen Sie Folgendes zur action-Funktion hinzu:
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},
  );
}

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 und beim Hinzufügen, Entfernen und Ändern der Artikelmenge verwendet wird. Fügen Sie einen weiteren useEffect-Hook in der AddToCartButton-Komponente hinzu, der die trackCartUpdated-Funktion aufruft, sobald sich der Fetcher-Zustand ändert (d. h. wenn der Warenkorb aktualisiert wird):
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>
  );
}
  1. Verwenden Sie denselben fetcherKey für die Aktionen, die für das Aktualisieren eines bestehenden Produkts in Ihrem Warenkorb zuständig sind. Fügen Sie Folgendes zu den Komponenten CartLineRemoveButton und CartLineUpdateButton hinzu (standardmäßig in der Datei 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>
  );
}

Braze-Shopify-Integration installieren

Schritt 1: Ihren Shopify-Shop verbinden

Rufen Sie die Shopify-Partnerseite auf, um mit der Einrichtung zu beginnen. 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.

Die benutzerdefinierte Einrichtung enthält eine Website-App-Auswahl. Wählen Sie die App aus, die Ihren 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 Einzelheiten finden Sie unter Schritt 1: Website-App auswählen und SDK-Zugangsdaten kopieren.

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

Einrichtungsschritt zur Aktivierung 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. Detaillierte Informationen zu den Daten, die durch diese Integration erfasst 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-Datenladevorgang wie bei der Standard-Integration einbeziehen: Bestellevents der letzten 90 Tage und Nutzerprofile des letzten Jahres, jeweils zurückgerechnet vom Datum Ihres Integrationsabschlusses. Um diesen initialen Datenladevorgang einzubeziehen, aktivieren Sie das Kontrollkästchen für die Option des initialen Datenladevorgangs.

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

Bereich zur Einrichtung des historischen Daten-Backfills.

Die vollständige Liste der Daten im initialen 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
  • Verwendung eines benutzerdefinierten Rabattcodes
  • Interaktion mit einer personalisierten Produktempfehlung
  • Lieblingsmarken oder -produkte
  • Bevorzugte Einkaufskategorien
  • Mitgliedschafts- oder Kundenbindungsstatus

Das SDK muss auf dem Gerät der Nutzerin bzw. des Nutzers initialisiert sein (auf Aktivitäten lauschen), um Events oder angepasste Attribute zu protokollieren. Weitere Informationen zum Protokollieren benutzerdefinierter Daten finden Sie unter User object und logCustomEvent.

Schritt 6: Nutzerverwaltung konfigurieren (optional)

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

Bereich „Abonnent:innen erfassen“.

Standardmäßig konvertiert Braze E-Mail-Adressen aus Shopify automatisch in Kleinbuchstaben, bevor sie als externe ID verwendet werden. Wenn Sie eine E-Mail-Adresse oder eine gehashte E-Mail-Adresse 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 Metafeld braze.external_id 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:

  • Kund:innenerstellungs-Webhooks abhören: Richten Sie einen Webhook ein, der auf customer/create-Events lauscht. So können Sie das Metafeld schreiben, wenn neue Kund:innen erstellt werden.
  • Bestehende Kund:innen nachträglich befüllen: Verwenden Sie die Admin API oder die 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. Dadurch kann Braze die ID in Szenarien abrufen, in denen Shopify das Metafeld braze.external_id nicht direkt bereitstellen kann.

Endpunktspezifikationen

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. Beispiel: <storefront_name>.myshopify.com
email_address Nein String Die E-Mail-Adresse der angemeldeten Nutzerin bzw. des angemeldeten Nutzers.

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

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, der die externe ID als JSON zurückgibt:

1
2
3

{
  "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 die Customer API verwenden, um diese Parameter zu validieren und das korrekte Metafeld braze.external_id 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 aus Shopify erfassen (optional)

Sie haben die Möglichkeit, Ihre E-Mail- oder SMS-Marketing-Opt-ins aus 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 aus Shopify synchronisieren, erstellt Braze automatisch eine E-Mail-Abo-Gruppe für alle Nutzer:innen, die mit diesem bestimmten Shop verknüpft sind. Sie müssen einen eindeutigen Namen für diese Abo-Gruppe erstellen.

Bereich „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 tiefere Messaging-Personalisierung zu ermöglichen. Automatische Aktualisierungen 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, Content Cards und Feature-Flags über die direkte Shopify-Integration zu aktivieren, fügen Sie jeden Kanal zu Ihrem SDK hinzu. Folgen Sie den für jeden Kanal bereitgestellten Dokumentationslinks:

  • In-App Messages: Informationen zur Aktivierung von In-App Messages für Lead-Erfassungsformular-Anwendungsfälle finden Sie unter In-App Messages.
  • Content Cards: Informationen zur Aktivierung von Content Cards für Posteingangs- oder Website-Banner-Anwendungsfälle finden Sie unter Content Cards.
  • Feature-Flags: Informationen zur Aktivierung von Feature-Flags für Website-Experimentierungs-Anwendungsfälle finden Sie unter 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 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-Hydrogen-App, die den gesamten Code aus den vorherigen Schritten enthält.
New Stuff!