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 Nutzerverhalten, 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:

Initialisieren und laden Sie das Braze Web SDK

1. Schritt: Erstellen Sie eine Braze-Website-App

Gehen Sie in Braze zu Einstellungen > App-Einstellungen und wählen Sie dann App hinzufügen. Geben Sie „Shopify“ als App-Namen ein.

2. Schritt: Subdomain und Umgebungsvariablen hinzufügen

  1. Richten Sie Ihre Shopify-Subdomain ein, um den Traffic von Ihrem Online-Shop auf 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 den Werten aus der Website-App, die Sie in Schritt 1 erstellt haben.
    • BRAZE_API_KEY
    • BRAZE_API_URL

3. Schritt: Onsite-Tracking aktivieren

Der erste Schritt besteht darin, das Braze Web SDK zu initialisieren. Wir empfehlen, dazu unser NPM-Paket zu installieren:

1
2
3

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

Nehmen Sie dann diese Einstellung als Top-Level-Schlüssel in Ihre vite.config.js-Datei auf:

1
2
3

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

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

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 mithilfe der in Schritt 2 erstellten Umgebungsvariablen in den Komponentenlader aufgenommen werden:

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

4. Schritt: Ein Shopify-Konto-Anmelde-Event hinzufügen

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

Bevor Sie beginnen, vergewissern Sie sich, dass Sie die Callback-URIs für die Kundenanmeldung so eingerichtet haben, dass sie in Hydrogen funktionieren. Weitere Informationen finden Sie unter Verwendung der Customer Account API mit Hydrogen.

  1. Nachdem Sie die Callback-URIs eingerichtet haben, definieren Sie eine Funktion für den Aufruf 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 in demselben 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:innen 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,
    },
  };
}

5. Schritt: Tracking für die Events „Produkt angesehen“ und „Warenkorb aktualisiert“ hinzufügen

Events „Produkt angesehen“

  1. Fügen Sie diese Funktion in Ihre Tracking.jsx-Datei ein:
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 vorherige Funktion immer dann aufzurufen, wenn Nutzer:innen eine Produktseite besuchen, fügen Sie der Product-Komponente in der Datei app/routes/products.$handle.jsx einen useEffect-Hook 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 Komponentenlader 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,
  };
}

Events „Warenkorb aktualisiert“

  1. Definieren Sie Funktionen für das Tracking des cart_updated-Events und das 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 von der Fetcher-Aktion zurück, damit Braze auf seine Eigenschaften zugreifen kann. Gehen Sie dazu in Ihre 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. Diese wird beim Hinzufügen, Entfernen und Ändern der Menge von Artikeln im Warenkorb verwendet. Fügen Sie einen weiteren useEffect-Hook in die AddToCartButton-Komponente ein, der die Funktion trackCartUpdated aufruft, sobald sich der Zustand des Formular-Fetchers ä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 Update eines bestehenden Produkts in Ihrem Warenkorb verantwortlich sind. Fügen Sie Folgendes zu den Komponenten CartLineRemoveButton und CartLineUpdateButton hinzu (die sich standardmäßig in der Datei app/components/CartLineItem.jsx befinden):
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>
  );
}

Installieren Sie die Braze Shopify-Integration

1. Schritt: Verbinden Sie Ihren Shopify-Shop

Rufen Sie die Shopify-Partnerseite auf, um Ihre 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 Installationsvorgang abzuschließen.

Einrichtungsseite für die Shopify-Integration im Braze-Dashboard.

2. Schritt: Braze SDKs aktivieren

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

Bevor Sie mit dem Onboarding-Prozess fortfahren, vergewissern Sie sich, dass Sie das Braze SDK auf Ihrer Shopify-Website aktiviert haben.

Einrichtungsschritt zur Aktivierung der Braze SDKs.

3. Schritt: Shopify-Daten tracken

Verbessern 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 durch diese Integration getrackt werden, finden Sie unter Shopify-Daten-Features.

Einrichtungsschritt zum Tracking von Shopify-Daten.

4. Schritt: Historisches Backfill (optional)

Durch die angepasste Einrichtung können Sie optional denselben historischen Shopify-Datenladevorgang wie bei der Standard-Integration einbeziehen: Bestell-Events der letzten 90 Tage und Nutzerprofile des letzten Jahres, jeweils ab dem Datum Ihrer Integrationsfertigstellung zurückgerechnet. Um diesen initialen Datenladevorgang einzubeziehen, aktivieren Sie das Kontrollkästchen für die Option zum initialen Datenladen.

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 Einrichten 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 Historisches Backfill.

5. Schritt: Angepasstes Daten-Tracking einrichten (erweitert)

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

5. Schritt: Angepasstes Daten-Tracking einrichten (erweitert)
Angepasste Events Angepasste Attribute
  • Einen angepassten Rabattcode verwenden
  • Mit einer personalisierten Produktempfehlung interagieren
  • Bevorzugte Marken oder Produkte
  • Bevorzugte Einkaufskategorien
  • Mitgliedschafts- oder Treuestatus

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

6. Schritt: Konfigurieren Sie, wie Sie Nutzer:innen verwalten (optional)

Wählen Sie Ihren external_id-Typ aus der Dropdown-Liste aus.

Abschnitt „Abonnent:innen sammeln“.

Standardmäßig wandelt Braze E-Mails von Shopify automatisch in Kleinbuchstaben um, bevor sie als externe ID verwendet werden. Wenn Sie E-Mail oder gehashte E-Mail als externe ID verwenden, vergewissern Sie sich, dass Ihre E-Mail-Adressen ebenfalls in Kleinbuchstaben umgewandelt 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 Settings > Metafields.
  2. Wählen Sie Customers > Add definition.
  3. Geben Sie für Namespace and key den Wert braze.external_id ein.
  4. Wählen Sie unter Type den ID Type aus.

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

  • Auf Webhooks zur Kundenerstellung lauschen: Richten Sie einen Webhook ein, um auf customer/create-Events zu lauschen. So können Sie das Metafeld schreiben, wenn neue Kund:innen angelegt 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 zu befüllen.

Schritt 6.2: Einen Endpunkt zum Abrufen Ihrer externen ID erstellen

Sie müssen einen öffentlichen Endpunkt erstellen, den Braze zum Abrufen der externen ID aufrufen kann. Dadurch kann Braze die ID in Szenarien 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 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 hier Null-Werte berücksichtigen (z. B. die E-Mail ü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, 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 braze.external_id-Metafeld abzurufen.

Fehlerverhalten und Zusammenführung

Jeder andere Statuscode als 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 wird die Zusammenführung zwischen dem Shopify-Nutzer und dem Braze-Nutzerprofil zu diesem Zeitpunkt nicht stattfinden.
  • Wiederholungslogik: Braze kann standardmäßige sofortige Netzwerk-Wiederholungsversuche unternehmen. Wenn der Fehler jedoch weiterhin besteht, wird die Zusammenführung bis zum nächsten qualifizierenden Event aufgeschoben (z. B. wenn Nutzer:innen 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 zuverlässig 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 Ihren externen Braze-ID-Typ ausgewählt haben.

Hinweise
  • Wenn Ihre externe ID zum Zeitpunkt der Braze-Anfrage an Ihren Endpunkt noch nicht generiert wurde, verwendet die Integration standardmäßig die Shopify-Kunden-ID, wenn die Funktion changeUser aufgerufen wird. Dieser Schritt ist entscheidend für die Zusammenführung des anonymen Nutzerprofils mit dem identifizierten Nutzerprofil. 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, wird die Integration diese externe ID priorisieren und zuweisen.
    • Wenn die Shopify-Kunden-ID zuvor als externe Braze-ID festgelegt wurde, wird sie durch den Wert des Metafelds braze.external_id ersetzt.

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

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

Wenn Sie die E-Mail- oder SMS-Kanäle nutzen, können Sie Ihre E-Mail- und SMS-Marketing-Opt-in-Status mit 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 Shop verknüpft sind. Sie müssen einen eindeutigen Namen für diese Abo-Gruppe erstellen.

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

7. Schritt: Produkte synchronisieren (optional)

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

Einrichtungsschritt zur Synchronisierung von Produktdaten mit Braze.

8. Schritt: Kanäle aktivieren

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

  • In-App-Nachrichten: Informationen zur Aktivierung von In-App-Nachrichten für Lead-Capture-Formular-Anwendungsfälle finden Sie unter In-App-Nachrichten.
  • 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-Experimentier-Anwendungsfälle finden Sie unter Feature-Flags.

9. Schritt: Einrichtung abschließen

Nachdem Sie alle Schritte durchlaufen haben, wählen Sie Finish Setup, um zur Partnerseite zurückzukehren. Aktivieren Sie dann die Braze-App-Einbettung auf Ihrer Shopify-Admin-Seite, wie durch das angezeigte Banner angezeigt.

Banner, das Sie auffordert, die Braze-App-Einbettung in Shopify zu aktivieren, damit Sie die Einrichtung Ihrer Integration abschließen können.

Beispiel-Code

shopify-hydrogen-example ist eine beispielhafte Hydrogen-App, die den gesamten Code enthält, der in den vorherigen Schritten behandelt wurde.
New Stuff!