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 Braze Web SDK

Etapa 1: Selecione um app de website e copie 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 ainda não conectou sua loja, conclua Conectar sua loja Shopify, depois continue com Ativar Braze SDKs 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 dar qualquer nome ao app, exceto Shopify, que a Braze reserva para o caminho de integração padrão do Shopify.
2. A Braze exibe a chave de API e a URL base (seu endpoint de SDK) do app selecionado 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 seu 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 Shopify.

Aviso

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

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

Importante

A versão mínima suportada do Braze Web SDK é a 5.4.0. Para integrações personalizadas do Shopify (incluindo lojas headless), você recebe notificações quando novas versões do SDK estão disponíveis, mas você gerencia as atualizações do seu lado, atualizando tanto o código da sua loja quanto a versão do SDK nas configurações de 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']
}

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

Nota

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

Etapa 4: Adicionar um evento de login de conta Shopify

Rastreie quando um comprador faz login na conta e sincroniza 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

Atualmente, não temos orientações para suportar 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, certifique-se de que você configurou os URIs de retorno de chamada para que o login do cliente funcione no Hydrogen. Para saber mais, consulte Using the Customer Account API with Hydrogen.

1. Após configurar os URIs de retorno de chamada, defina uma função para chamar o Braze SDK. 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);
  }
}

2. No mesmo hook useEffect que inicializa o Braze SDK, adicione a chamada a 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: Adicionar rastreamento para eventos Product Viewed e Cart Updated

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

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 para “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 Cart Updated

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

2. Retorne o objeto cart da ação do fetcher para que a Braze possa acessar suas propriedades, acessando 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 fetchers do Remix, consulte useFetcher.

3. As lojas Hydrogen geralmente definem um componente CartForm que gerencia o estado do objeto de carrinho, usado ao adicionar, remover e alterar a quantidade de itens no 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>
  );
}

4. Use o mesmo 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 do Shopify para iniciar sua configuração. Primeiro, selecione Begin Setup para instalar o aplicativo Braze na Shopify App Store. Siga as etapas guiadas para concluir o processo de instalação.

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 de website. Selecione ou crie o app que alimenta sua vitrine e, em seguida, copie a chave de API e o endpoint de SDK mostrados na etapa de integração. Para mais detalhes, consulte Etapa 1: Selecionar um app de 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 3: Rastrear dados do Shopify

Aprimore 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 4: Preenchimento histórico (opcional)

Por meio da configuração personalizada, você pode opcionalmente incluir o mesmo carregamento 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, contados a partir da data em que você concluiu a integração. Para incluir esse carregamento inicial de dados, marque a caixa de seleção da opção de carregamento inicial de dados.

Se preferir realizar o preenchimento posteriormente, você pode concluir a configuração inicial agora e retornar a essa etapa mais tarde.

Para a lista completa de dados no carregamento inicial, comportamento de relatórios de receita e monitoramento da 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. Eventos personalizados capturam interações exclusivas na sua loja, como:

O SDK precisa estar 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.

Importante

Usar um endereço de e-mail ou um endereço de e-mail com hash como seu ID externo da Braze pode ajudar a simplificar o gerenciamento de identidade entre suas fontes de dados. No entanto, é importante considerar os riscos potenciais à privacidade do usuário e à segurança dos dados.

• Informações previsíveis: endereços de e-mail são facilmente previsíveis, tornando-os vulneráveis a ataques.
• Risco de exploração: se um usuário mal-intencionado alterar seu navegador web para enviar o endereço de e-mail de outra pessoa como seu ID externo, ele poderá acessar mensagens sensíveis ou informações da conta.

Por padrão, a Braze converte automaticamente os e-mails do Shopify para 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 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 da sua seleção de ID externo:

• Se você selecionou um tipo de ID externo personalizado: conclua as etapas 6.1–6.3 para configurar seu ID externo personalizado.
• Se você selecionou Shopify customer ID, e-mail ou e-mail com hash: pule as etapas 6.1–6.3 e continue diretamente para a etapa 6.4.

Etapa 6.1: Criar o metafield 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 metafield, preencha-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ê preencha o metafield quando um novo cliente é criado.
• Preencher clientes existentes: use a Admin API ou a Customer API para preencher o metafield para 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 obtenha o ID em cenários em que o Shopify não pode fornecer o metafield 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 que o shopify_customer_id e o email_address (se presente) correspondem 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 metafield 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)

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

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

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 de 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 Use Braze SMS double opt-in.

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

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 mais profunda de mensagens. 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 8: Ativar canais

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

• In-App Messages: para ativar In-App Messages para casos de uso de formulários de captura de leads, consulte In-App Messages.
• Banners: para ativar Banners para casos de uso de personalização da vitrine Shopify, consulte Banners.
• Feature Flags: para ativar Feature Flags para casos de uso de experimentação na vitrine Shopify, consulte Feature Flags.

Etapa 9: Finalizar a configuração

Depois de concluir todas as etapas, selecione Finish Setup para retornar à página de parceiro. Em seguida, ative a incorporação do app Braze na sua página de administração do 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.