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.

2. 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.

Importante

Antes de iniciar sua integração, confirme que você configurou corretamente o subdomínio de checkout para sua vitrine do Shopify. Para saber mais, consulte Migrar da loja on-line para o Hydrogen.

Se essa configuração não for feita corretamente, a Braze não poderá processar os webhooks de checkout do Shopify. Também não será possível testar a integração em um ambiente de desenvolvimento local, pois isso depende de um domínio compartilhado entre a vitrine e a página de checkout.

Para concluir essas metas, siga estas etapas:

Inicializar e carregar o Web SDK da Braze

Etapa 1: Selecione um app de site e copie as credenciais do SDK

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

No fluxo de configuração personalizada, a Braze pede que você selecione o app de site da sua loja headless:

1. Selecione um app de site existente ou crie um novo. Você pode dar qualquer nome ao app, exceto Shopify, que a Braze reserva para o caminho de integração padrão da Shopify.
2. A Braze exibe a chave de API e o URL base (seu endpoint do SDK) do app selecionado na etapa de integração. Selecione Copiar para cada valor. Não é necessário abrir Configurações > Configurações do app.
3. Use a chave de API copiada como BRAZE_API_KEY e o endpoint do SDK como BRAZE_API_URL nas variáveis de ambiente da Shopify (Etapa 2).

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

Aviso

Use a chave de API do app de site que você selecionou durante a integração. Se o seu ambiente Hydrogen usar uma chave de API diferente da conectada à sua integração com a Shopify, a Braze poderá criar usuários duplicados e os métodos do SDK poderão não funcionar como esperado.

Etapa 2: Adicione o subdomínio e as variáveis de ambiente

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

Etapa 3: Ative o rastreamento no site

O primeiro passo é inicializar o Web SDK da Braze. 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

Importante

A versão mínima compatível do Web SDK da Braze é a 5.4.0. Nas integrações personalizadas da Shopify (incluindo lojas headless), você recebe notificações quando novas versões do SDK ficam disponíveis, mas é você quem gerencia os upgrades, atualizando tanto o código da sua loja quanto a versão do SDK nas configurações da integração.

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']
}

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

Nota

As políticas de segurança de conteúdo (geralmente localizadas no arquivo entry.server.jsx do Hydrogen) podem afetar o funcionamento dos scripts da Braze tanto em ambientes locais quanto de produção. Sugerimos testar por meio de builds de prévia enviados à Shopify pelo Oxygen ou por implementações personalizadas. Se tiver problemas, você precisará configurar sua CSP para permitir que nosso JavaScript funcione.

Etapa 4: Adicione um evento de login na conta Shopify

Rastreie quando um comprador entra na conta e sincronize as informações do usuário com a Braze. Isso inclui chamar nosso método changeUser para identificar clientes com um ID externo da Braze.

Nota

No momento, não temos orientações para oferecer suporte a um ID externo personalizado da Braze. Se você precisar disso para sua integração agora, entre em contato com seu gerente de sucesso do cliente.

Antes de começar, confira se você configurou os URIs de retorno de chamada para que o login do cliente funcione no Hydrogen. Para saber mais, consulte Usar a Customer Account API com o 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 a partir 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);
  }
}

2. No mesmo hook useEffect que inicializa o SDK da Braze, adicione a chamada para essa 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])

3. Busque o endereço de e-mail e o número de telefone do cliente na sua consulta GraphQL da Customer API, 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
  }
`;

4. 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: Adicione o rastreamento dos eventos de produto visualizado e carrinho atualizado

Eventos de produto visualizado

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

2. 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 (...)
}

3. 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 carrinho atualizado

Importante

Para esta integração, o alias de usuário deve usar o seguinte formato para que a Braze possa associar os webhooks ao perfil de usuário correto:

• alias_label: shopify_cart_${cartToken}
• alias_name: shopify_cart_token

1. Defina funções para rastrear o evento cart_updated e definir 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);
    }
  }
}

2. Retorne o objeto cart da ação do fetcher para que a Braze possa acessar as propriedades dele. Para isso, acesse o arquivo app/routes/cart.jsx e adicione 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.

3. As lojas Hydrogen geralmente definem um componente CartForm que gerencia o estado do objeto do carrinho, usado ao adicionar, remover e alterar a quantidade de itens em um carrinho. Adicione outro hook useEffect no componente AddToCartButton que chame a função trackCartUpdated sempre que o estado do fetcher do formulário mudar (ou seja, 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>
  );
}

4. Use o mesmo fetcherKey nas ações responsáveis por atualizar um produto que já está no 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 da Braze com a Shopify

Etapa 1: Conecte sua loja da Shopify

Acesse a página de parceiro da Shopify para iniciar a configuração. Primeiro, selecione Iniciar configuração para instalar o aplicativo da Braze pela Shopify App Store. Depois, siga as etapas guiadas para concluir a instalação.

Etapa 2: Ative os SDKs da Braze

Para lojas Shopify Hydrogen ou headless, selecione a opção Configuração personalizada.

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

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

Etapa 3: Rastreie dados da Shopify

Aprimore sua integração adicionando mais eventos e atributos da Shopify, que serão alimentados pelos webhooks da Shopify. Para saber mais sobre os dados rastreados por essa integração, consulte Recursos de dados da Shopify.

Etapa 4: Preenchimento histórico (opcional)

Na configuração personalizada, você pode incluir opcionalmente o mesmo carregamento de dados históricos da Shopify disponível na integração padrão.

Selecione Ativar preenchimento histórico e escolha um intervalo de datas para pedidos (Últimos 90 dias, Último ano ou Últimos 2 anos) e para perfis de clientes (Último ano, Últimos 2 anos ou Todo o período). Essas seleções não podem ser alteradas depois que a configuração for concluída.

Se preferir fazer o preenchimento depois, você pode concluir a configuração inicial agora e voltar a esta etapa mais tarde.

Para ver a lista completa de dados incluídos no carregamento inicial, o comportamento dos relatórios de receita e como monitorar a sincronização, consulte Preenchimento histórico.

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. Os eventos personalizados capturam interações exclusivas na sua loja, como:

O SDK precisa estar inicializado (ouvindo a atividade) no dispositivo do usuário para registrar eventos ou atributos personalizados. Para saber mais sobre como registrar dados personalizados, consulte Objeto de usuário e logCustomEvent.

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

Selecione o tipo de external_id no menu suspenso.

Importante

Usar um endereço de e-mail ou um endereço de e-mail com hash como ID externo na Braze pode simplificar o gerenciamento de identidades entre suas fontes de dados. No entanto, é importante considerar os possíveis riscos à privacidade dos usuários e à segurança dos dados.

• Informações fáceis de adivinhar: Endereços de e-mail são fáceis de adivinhar, o que os torna vulneráveis a ataques.
• Risco de exploração: Se um usuário mal-intencionado alterar o navegador web para enviar o endereço de e-mail de outra pessoa como ID externo, ele poderá acessar mensagens confidenciais ou informações da conta.

Por padrão, a Braze converte automaticamente os e-mails da Shopify para letras minúsculas antes de usá-los como ID externo. Se você usa e-mail ou e-mail com hash como ID externo, confirme que seus endereços de e-mail também são convertidos para minúsculas antes de atribuí-los como 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.

Nota

As próximas etapas dependem do ID externo selecionado:

• Se você selecionou um tipo de ID externo personalizado: Conclua as etapas 6.1 a 6.3 para configurar seu ID externo personalizado.
• Se você selecionou ID de cliente da Shopify, e-mail ou e-mail com hash: Pule as etapas 6.1 a 6.3 e siga diretamente para a etapa 6.4.

Etapa 6.1: Crie o metacampo braze.external_id

1. Na página 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.

Depois de criar o metacampo, preencha-o para seus clientes. Recomendamos as seguintes abordagens:

• Ouvir webhooks de criação de clientes: Configure um webhook para ouvir eventos customer/create. Assim, você pode gravar o metacampo quando um novo cliente for criado.
• Preencher clientes existentes: Use a Admin API ou a Customer API para preencher o metacampo de clientes criados anteriormente.

Etapa 6.2: Crie um endpoint para obter seu ID externo

Você precisa criar um endpoint público que a Braze possa chamar para obter o ID externo. Isso permite que a Braze busque o ID em cenários em que a Shopify não consegue 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:

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 se shopify_customer_id e email_address (se presente) correspondem aos valores do cliente na Shopify. Você pode usar a Shopify Admin API ou a Customer API para validar esses parâmetros e obter 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: Informe seu ID externo

Repita a Etapa 6 e insira a URL do seu endpoint depois de selecionar o ID externo personalizado como tipo de ID externo na 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: Colete as aceitações de e-mail ou SMS da Shopify (opcional)

Se você usa os canais de e-mail, SMS ou WhatsApp, pode sincronizar os estados de aceitação de marketing por e-mail, SMS e WhatsApp do Shopify com a Braze.

• e-mail
• dupla aceitação de sms
• whatsapp

Se você sincronizar as aceitações de marketing por e-mail do Shopify, a Braze cria 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.

Nota

Conforme mencionado na visão geral do Shopify, se você quiser usar um formulário de captura de terceiros, seus desenvolvedores precisarão integrar o código do SDK da Braze. Isso permitirá capturar o endereço de e-mail e o status global de inscrição de e-mail a partir dos envios de formulário. Especificamente, você precisa implementar e testar estes métodos no seu arquivo theme.liquid:

• setEmail: Define o endereço de e-mail no perfil de usuário
• setEmailNotificationSubscriptionType: Atualiza o status global de inscrição de e-mail

Use a dupla aceitação de SMS para enviar seu texto de confirmação personalizado pela Braze em vez do e-mail de confirmação do Shopify. Para ativar a dupla aceitação de SMS:

1. No painel de administração do Shopify, acesse Configurações > Notificações > Notificações para clientes.
2. Desative a dupla aceitação de marketing para SMS.
3. Defina o SMS de checkout como aceitação única.
4. Nas configurações de SMS da Braze, selecione Usar a dupla aceitação de SMS da Braze.

Para saber mais sobre a dupla aceitação de SMS da Braze e o fluxo de inscritos, consulte Visão geral do Shopify.

Se você envia mensagens de WhatsApp pela Braze, também pode sincronizar as aceitações de marketing por WhatsApp do Shopify. Selecione Coletar inscritos do WhatsApp e, em seguida, selecione os grupos de inscrições do WhatsApp que serão sincronizados.

Importante

Seu espaço de trabalho precisa ter uma conta do WhatsApp Business conectada para ter grupos de inscrições do WhatsApp. Conecte uma em Parceiros de tecnologia > WhatsApp.

A Braze sincroniza apenas o consentimento de WhatsApp que o Shopify armazena para um cliente. Uma aceitação de SMS ou e-mail não inscreve o cliente no WhatsApp, e não há dupla aceitação para o WhatsApp. Para saber mais, consulte Aceitações de marketing por WhatsApp.

Etapa 7: Sincronize produtos (opcional)

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

Etapa 8: Ative os canais

Para ativar mensagens no app, Banners e Feature Flags usando a integração direta com a Shopify, adicione cada canal ao seu SDK. Siga os links da documentação de cada canal:

• Mensagens no app: Para ativar mensagens no app em casos de uso de formulários de captura de leads, consulte Mensagens no app.
• Banners: Para ativar Banners em casos de uso de personalização da vitrine da Shopify, consulte Banners.
• Feature Flags: Para ativar Feature Flags em casos de uso de experimentação na vitrine da Shopify, consulte Feature Flags.

Etapa 9: Conclua a configuração

Depois de passar por todas as etapas, selecione Concluir configuração para voltar à página de parceiro. Em seguida, ative a incorporação do app da Braze na página de administração da Shopify, conforme indicado pelo banner exibido.

Exemplo de código

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