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: 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 com configuração personalizada. Se você ainda não conectou sua loja, conclua Conectar sua loja Shopify e continue com Ativar SDKs da Braze, selecionando 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 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 acessar 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).

Após 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.

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 conectada à sua integração com o Shopify, a Braze poderá criar usuários duplicados e os métodos do SDK poderão não funcionar conforme esperado.

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

1. Configure seu subdomínio do 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 com 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 é responsável por gerenciar os upgrades, 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 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 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 por 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 da 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

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, verifique se 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 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 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])

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

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 de 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 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 suas propriedades, acessando o 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. 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 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>
  );
}

Instale a integração Braze Shopify

Etapa 1: Conecte sua loja Shopify

Acesse a página de parceiro do 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.

Etapa 2: Ative 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 para 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: Selecione um app para website e copie 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: Rastreie 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 de dados históricos (opcional)

Através da configuração personalizada, você pode opcionalmente incluir o mesmo carregamento de dados históricos do Shopify da integração padrão: eventos de pedidos dos últimos 90 dias e perfis de usuários do último ano, cada um contado a partir da data em que você concluir sua integração. Para incluir esse carregamento inicial de dados, marque a caixa de seleção para a opção de carregamento inicial de dados.

Se você preferir realizar o preenchimento de dados históricos depois, pode concluir a configuração inicial agora e voltar a essa etapa mais tarde.

Para a lista completa de dados no carregamento 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 exclusivas na sua loja, como:

O SDK deve estar inicializado (ouvindo atividade) 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: Configure 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 de dados.

• Informação previsível: 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 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.

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 a 6.3 para configurar seu ID externo personalizado.
• Se você selecionou ID de cliente Shopify, e-mail ou e-mail com hash: Pule as etapas 6.1 a 6.3 e continue diretamente para a etapa 6.4.

Etapa 6.1: Crie 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:

• Ouça webhooks de criação de clientes: Configure um webhook para ouvir eventos customer/create. Isso permite que você escreva o metafield quando um novo cliente é criado.
• Preencha os dados de clientes existentes: Use a Admin API ou a Customer API para preencher o metafield para clientes criados anteriormente.

Etapa 6.2: Crie um endpoint para recuperar seu ID externo

Você deve 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 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

É essencial 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: Insira seu ID externo

Repita a Etapa 6 e insira a URL do seu endpoint após selecionar o tipo de 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: Colete 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ê usa os canais de e-mail ou SMS, pode sincronizar os estados de aceitação de marketing por e-mail e SMS na Braze. Se você sincronizar 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.

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

Etapa 7: Sincronize produtos (opcional)

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

Etapa 8: Ative 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 de loja Shopify, consulte Banners.
• Feature Flags: Para ativar Feature Flags para casos de uso de experimentação na loja Shopify, consulte Feature Flags.

Etapa 9: Finalize a configuração

Após passar por 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.

Código de exemplo

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