Skip to content

Configuração da integração personalizada do Shopify

Esta página orienta você sobre como integrar a Braze a uma loja Shopify Hydrogen ou a qualquer loja Shopify headless usando uma vitrine personalizada.

Este guia usa o framework Hydrogen da Shopify como exemplo. No entanto, você pode seguir uma abordagem semelhante se a sua marca usar o Shopify para o backend da sua loja com uma configuração de front-end “headless”.

Para integrar sua loja Shopify headless com a Braze, você precisa concluir estas duas metas:

  1. Inicializar e carregar o Braze Web SDK para ativar o rastreamento no site

    Adicione manualmente o código em seu site do Shopify para ativar o rastreamento no site da Braze. Ao implementar o Braze SDK em sua loja Shopify headless, é possível rastrear as atividades no site, incluindo sessões, comportamento de usuário anônimo, ações do comprador antes do checkout e quaisquer eventos personalizados ou atributos personalizados que você decida incluir com sua equipe de desenvolvimento. Você também pode adicionar quaisquer canais compatíveis com os SDKs, como In-App Messages ou Content Cards.
  1. Instalar a integração da Braze com o Shopify

    Depois de conectar sua loja Shopify à Braze, você terá acesso aos dados de clientes, checkout, pedidos e produtos por meio de webhooks do Shopify.

Para concluir essas metas, siga estas etapas:

Inicializar e carregar o Braze Web SDK

Etapa 1: Selecionar um app de website e copiar as credenciais do SDK

Antes de adicionar código à sua loja Hydrogen, conecte sua loja Shopify e inicie a integração de configuração personalizada. Se você ainda não conectou sua loja, conclua Conectar sua loja Shopify e, em seguida, prossiga com Ativar os SDKs da Braze e selecione Custom setup.

No fluxo de configuração personalizada, a Braze solicita que você selecione o app de website para sua loja headless:

  1. Selecione um app de website existente ou crie um novo. Você pode nomear o app com qualquer nome, exceto Shopify, que a Braze reserva para o caminho de integração padrão do Shopify.
  2. A Braze exibe a chave de API do app selecionado e a URL base (seu endpoint de SDK) na etapa de integração. Selecione Copy para cada valor — não é necessário abrir Settings > App Settings.
  3. Use a chave de API copiada como BRAZE_API_KEY e o endpoint de SDK como BRAZE_API_URL nas variáveis de ambiente do Shopify (Etapa 2).

Depois de conectar a loja, você pode renomear o app de website selecionado em Settings > App Settings. Não é possível excluir o app enquanto ele estiver conectado à sua integração com o Shopify.

Etapa 2: Adicionar subdomínio e variáveis de ambiente

  1. Configure seu subdomínio Shopify para redirecionar o tráfego da sua loja online para o Hydrogen.
  2. Adicione um URI de retorno de chamada para login. (O URI será adicionado automaticamente quando o domínio for adicionado.)
  3. Configure suas variáveis de ambiente do Shopify:
    • Crie duas variáveis de ambiente usando a chave de API e o endpoint de SDK que você copiou durante a integração de configuração personalizada na Etapa 1.
    • BRAZE_API_KEY
    • BRAZE_API_URL

Etapa 3: Ativar o rastreamento no site

A primeira etapa é inicializar o Braze Web SDK. Recomendamos fazer isso instalando nosso pacote NPM:

1
2
3

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

Em seguida, inclua esta configuração como uma chave de nível superior no seu arquivo vite.config.js:

1
2
3

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

Após instalar o pacote NPM, você deve inicializar o SDK dentro de um hook useEffect no componente Layout. Dependendo da sua versão do Hydrogen, esse componente pode estar localizado no arquivo root.jsx ou 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 (...);
}

Os valores data.brazeApiKey e data.brazeApiUrl precisam ser incluídos no loader do componente usando as variáveis de ambiente criadas na Etapa 2:

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

Etapa 4: Adicionar um evento de login de conta Shopify

Rastreie quando um comprador faz login em sua conta e sincroniza suas informações de usuário com a Braze. Isso inclui chamar nosso método changeUser para identificar clientes com um ID externo da Braze.

Antes de começar, certifique-se de ter configurado os URIs de retorno de chamada para que o login do cliente funcione no Hydrogen. Para saber mais, consulte Usando a API de conta de cliente com Hydrogen.

  1. Depois de configurar os URIs de retorno de chamada, defina uma função para chamar o SDK da Braze. Crie um novo arquivo (como Tracking.jsx) e importe-o dos seus componentes:
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. No mesmo hook useEffect que inicializa o SDK da Braze, adicione a chamada a esta função:
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. Busque o endereço de e-mail e o número de telefone do cliente na sua consulta GraphQL da API de clientes, localizada no arquivo app/graphql/customer-account/CustomerDetailsQuery.js:
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. Por fim, carregue os dados do cliente na sua função loader:
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,
    },
  };
}

Etapa 5: Adicionar rastreamento para eventos de Product Viewed e Cart Updated

Eventos de Product Viewed

  1. Adicione esta função ao seu arquivo Tracking.jsx:
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. Para chamar a função anterior sempre que um usuário visitar uma página de produto, adicione um hook useEffect ao componente Product no arquivo app/routes/products.$handle.jsx:
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. Adicione o valor de “storefrontUrl” (porque ele não está no loader do componente por padrão):
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,
  };
}

Eventos de Cart Updated

  1. Defina funções para rastrear o evento cart_updated e configurar o token do carrinho:
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. Retorne o objeto cart da ação do fetcher para que a Braze possa acessar suas propriedades, indo ao seu arquivo app/routes/cart.jsx e adicionando o seguinte à função action:
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},
  );
}

Para saber mais sobre os fetchers do Remix, consulte useFetcher.

  1. Lojas Hydrogen geralmente definem um componente CartForm que gerencia o estado do objeto do carrinho, que é usado ao adicionar, remover e alterar a quantidade de itens em um carrinho. Adicione outro hook useEffect no componente AddToCartButton que chamará a função trackCartUpdated sempre que o estado do fetcher do formulário mudar (sempre que o carrinho do usuário for atualizado):
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. Use a mesma fetcherKey para as ações responsáveis por atualizar um produto existente no seu carrinho. Adicione o seguinte aos componentes CartLineRemoveButton e CartLineUpdateButton (localizados por padrão no arquivo 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>
  );
}

Instalar a integração Braze Shopify

Etapa 1: Conectar sua loja Shopify

Acesse a página de parceiro Shopify para iniciar sua configuração. Primeiro, selecione Begin Setup para instalar o aplicativo da Braze na Shopify App Store. Siga as etapas guiadas para concluir o processo de instalação.

Página de configuração da integração Shopify no dashboard da Braze.

Etapa 2: Ativar os SDKs da Braze

Para lojas Shopify Hydrogen ou headless, selecione a opção Custom setup.

A configuração personalizada inclui um seletor de app do website. Selecione ou crie o app que alimenta sua loja virtual e, em seguida, copie a chave de API e o endpoint de SDK exibidos na etapa de integração. Para mais detalhes, consulte Etapa 1: Selecionar um app do website e copiar as credenciais do SDK.

Antes de continuar com o processo de integração, confirme que você adicionou o SDK da Braze ao seu website Shopify usando essas credenciais.

Etapa de configuração para ativar os SDKs da Braze.

Etapa 3: Rastrear dados do Shopify

Melhore sua integração adicionando mais eventos e atributos do Shopify, que serão alimentados por webhooks do Shopify. Para informações detalhadas sobre os dados rastreados por essa integração, consulte Recursos de dados do Shopify.

Etapa de configuração para rastrear dados do Shopify.

Etapa 4: Preenchimento de dados históricos (opcional)

Por meio da configuração personalizada, você pode incluir opcionalmente a mesma carga de dados históricos do Shopify que a integração padrão: eventos de pedidos dos últimos 90 dias e perfis de usuário do último ano, cada um contado retroativamente a partir da data em que você concluir sua integração. Para incluir essa carga de dados inicial, marque a caixa de seleção da opção de carga de dados inicial.

Se você preferir fazer o preenchimento de dados históricos depois, pode concluir a configuração inicial agora e retornar a essa etapa em outro momento.

Seção para configurar o preenchimento de dados históricos.

Para a lista completa de dados na carga inicial, o comportamento de relatórios de receita e o monitoramento da sincronização, consulte Preenchimento de dados históricos.

Etapa 5: Configuração de rastreamento de dados personalizados (avançado)

Com os SDKs da Braze, você pode rastrear eventos personalizados ou atributos personalizados que vão além dos dados suportados por essa integração. Eventos personalizados capturam interações únicas na sua loja, como:

Etapa 5: Configuração de rastreamento de dados personalizados (avançado)
Eventos personalizados Atributos personalizados
  • Usar um código de desconto personalizado
  • Interagir com uma recomendação de produto personalizada
  • Marcas ou produtos favoritos
  • Categorias de compra preferidas
  • Status de membro ou de fidelidade

O SDK precisa ser inicializado (escutando atividades) no dispositivo do usuário para registrar eventos ou atributos personalizados. Para saber mais sobre o registro de dados personalizados, consulte User object e logCustomEvent.

Etapa 6: Configurar como você gerencia usuários (opcional)

Selecione o tipo de external_id no menu suspenso.

Seção "Coletar inscritos".

Por padrão, a Braze converte automaticamente os e-mails do Shopify para letras minúsculas antes de usá-los como ID externo. Se você estiver usando e-mail ou e-mail com hash como seu ID externo, confirme que seus endereços de e-mail também são convertidos para letras minúsculas antes de atribuí-los como seu ID externo ou antes de aplicar o hash a partir de outras fontes de dados. Isso ajuda a evitar discrepâncias nos IDs externos e a criação de perfis de usuário duplicados na Braze.

Etapa 6.1: Criar o metacampo braze.external_id

  1. No painel de administração do Shopify, acesse Settings > Metafields.
  2. Selecione Customers > Add definition.
  3. Em Namespace and key, insira braze.external_id.
  4. Em Type, selecione ID Type.

Após a criação do metacampo, popule-o para seus clientes. Recomendamos as seguintes abordagens:

  • Escutar webhooks de criação de clientes: Configure um webhook para escutar eventos customer/create. Isso permite que você grave o metacampo quando um novo cliente for criado.
  • Preencher dados de clientes existentes: Use a Admin API ou a Customer API para preencher o metacampo de clientes criados anteriormente.

Etapa 6.2: Criar um endpoint para recuperar seu ID externo

Você precisa criar um endpoint público que a Braze possa chamar para recuperar o ID externo. Isso permite que a Braze busque o ID em cenários onde o Shopify não pode fornecer o metacampo braze.external_id diretamente.

Especificações do endpoint

Método: GET

A Braze envia os seguintes parâmetros para o seu endpoint:

Parâmetro Obrigatório Tipo de dados Descrição
shopify_customer_id Sim String O ID de cliente do Shopify.
shopify_storefront Sim String O nome da loja virtual para a solicitação. Ex: <storefront_name>.myshopify.com
email_address Não String O endereço de e-mail do usuário conectado.

Esse campo pode estar ausente em certos cenários de webhook. A lógica do seu endpoint deve considerar valores nulos aqui (por exemplo, buscar o e-mail usando o shopify_customer_id caso sua lógica interna o exija).
Exemplo de endpoint
1

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

A Braze espera um código de status 200 retornando o JSON do ID externo:

1
2
3

{
  "external_id": "my_external_id"
}
Validação

É fundamental validar que o shopify_customer_id e o email_address (se presente) correspondam aos valores do cliente no Shopify. Você pode usar a Shopify Admin API ou a Customer API para validar esses parâmetros e recuperar o metacampo braze.external_id correto.

Comportamento em caso de falha e mesclagem

Qualquer código de status diferente de 200 é considerado uma falha.

  • Implicações da mesclagem: Se o endpoint falhar (retornar algo diferente de 200 ou expirar), a Braze não consegue recuperar o ID externo. Consequentemente, a mesclagem entre o usuário do Shopify e o perfil de usuário da Braze não acontece naquele momento.
  • Lógica de nova tentativa: A Braze pode tentar novas tentativas de rede imediatas padrão, mas se a falha persistir, a mesclagem é adiada até o próximo evento qualificado (por exemplo, a próxima vez que o usuário atualizar seu perfil ou concluir um checkout).
  • Suportabilidade: Para garantir a mesclagem de usuários em tempo hábil, certifique-se de que seu endpoint esteja altamente disponível e lide com o campo opcional email_address de forma adequada.

Etapa 6.3: Inserir seu ID externo

Repita a Etapa 6 e insira a URL do seu endpoint após selecionar ID externo personalizado como seu tipo de ID externo da Braze.

Considerações
  • Se o seu ID externo não for gerado quando a Braze enviar uma solicitação ao seu endpoint, a integração usará por padrão o ID de cliente do Shopify quando a função changeUser for chamada. Essa etapa é crucial para mesclar o perfil de usuário anônimo com o perfil de usuário identificado. Como resultado, pode haver um período temporário durante o qual diferentes tipos de IDs externos existem no seu espaço de trabalho.
  • Quando o ID externo estiver disponível no metafield braze.external_id, a integração priorizará e atribuirá esse ID externo.
    • Se o ID de cliente do Shopify foi definido anteriormente como o ID externo da Braze, ele será substituído pelo valor do metafield braze.external_id.

Etapa 6.4: Coletar suas aceitações de e-mail ou SMS do Shopify (opcional)

Você tem a opção de coletar suas aceitações de marketing por e-mail ou SMS do Shopify.

Se você utiliza os canais de e-mail ou SMS, pode sincronizar os estados de aceitação de marketing por e-mail e SMS com a Braze. Se você sincronizar as aceitações de marketing por e-mail do Shopify, a Braze criará automaticamente um grupo de inscrições para e-mail para todos os usuários associados a essa loja específica. Você precisa criar um nome exclusivo para esse grupo de inscrições.

Seção "Coletar inscritos" com opção para coletar aceitações de marketing por e-mail ou SMS.

Etapa 7: Sincronizar produtos (opcional)

Você pode sincronizar todos os produtos da sua loja Shopify com um catálogo da Braze para uma personalização de mensagens mais profunda. As atualizações automáticas ocorrem em tempo quase real, então seu catálogo sempre reflete os detalhes mais recentes dos produtos. Para saber mais, confira Sincronização de produtos do Shopify.

Etapa de configuração para sincronizar dados de produtos com a Braze.

Etapa 8: Ativar canais

Para ativar In-App Messages, Content Cards e Feature Flags usando a integração direta do Shopify, adicione cada canal ao seu SDK. Siga os links da documentação fornecidos para cada canal:

  • In-App Messages: Para ativar In-App Messages em casos de uso de formulários de captura de leads, consulte In-App Messages.
  • Content Cards: Para ativar Content Cards em casos de uso de caixa de entrada ou banners de website, consulte Content Cards.
  • Feature Flags: Para ativar Feature Flags em casos de uso de experimentação no site, consulte Feature Flags.

Etapa 9: Concluir a configuração

Após concluir todas as etapas, selecione Finish Setup para retornar à página de parceiro. Em seguida, ative o app embed da Braze na sua página de administração do Shopify, conforme indicado pelo banner exibido.

Banner informando para ativar o app embed da Braze no Shopify para concluir a configuração da integração.

Código de exemplo

shopify-hydrogen-example é um app Hydrogen de exemplo que contém todo o código abordado nas etapas anteriores.
New Stuff!