Configuración de la integración personalizada de Shopify

Esta página te explica cómo integrar Braze con una tienda Hydrogen de Shopify o con cualquier tienda headless de Shopify utilizando un escaparate personalizado.

Esta guía utiliza el framework Hydrogen de Shopify como ejemplo. Sin embargo, puedes seguir un enfoque similar si tu marca utiliza Shopify para el backend de tu tienda con una configuración de frontend “headless”.

Para integrar tu tienda headless de Shopify con Braze, necesitas completar estos dos objetivos:

1. Inicializar y cargar el SDK web de Braze para habilitar el seguimiento in situ
   
   Añade manualmente código en tu sitio web de Shopify para habilitar el seguimiento in situ de Braze. Al implementar el SDK de Braze en tu tienda headless de Shopify, puedes hacer un seguimiento de las actividades in situ, incluidas las sesiones, el comportamiento del usuario anónimo, las acciones del comprador previas al pago y cualquier evento personalizado o atributo personalizado que decidas incluir con tu equipo de desarrolladores. También puedes añadir cualquier canal admitido por los SDK, como mensajes dentro de la aplicación o Content Cards.

2. Instalar la integración Braze Shopify
   
   Cuando conectes tu tienda Shopify a Braze, tendrás acceso a los datos de clientes, pagos, pedidos y productos a través de los webhooks de Shopify.

Importante

Antes de iniciar la integración, confirma que has configurado correctamente el subdominio de pago para tu escaparate de Shopify. Para más información, consulta Migrar de la tienda online a Hydrogen.

Si esta configuración no se realiza correctamente, Braze no podrá procesar los webhooks de pago de Shopify. Tampoco será posible probar la integración en un entorno de desarrollo local, porque eso depende de un dominio compartido entre tu escaparate y la página de pago.

Para completar estos objetivos, sigue estos pasos:

Inicializar y cargar el SDK web de Braze

Paso 1: Selecciona una aplicación de sitio web y copia las credenciales del SDK

Antes de añadir código a tu escaparate Hydrogen, conecta tu tienda Shopify e inicia la incorporación de configuración personalizada. Si aún no has conectado tu tienda, completa Conectar tu tienda Shopify, luego continúa con Habilitar los SDK de Braze y selecciona Custom setup.

En el flujo de configuración personalizada, Braze te solicita que selecciones la aplicación de sitio web para tu escaparate headless:

1. Selecciona una aplicación de sitio web existente o crea una nueva. Puedes nombrar la aplicación como quieras, excepto Shopify, que Braze reserva para la ruta de integración estándar de Shopify.
2. Braze muestra la clave de API y la URL base (tu punto final de SDK) de la aplicación seleccionada en el paso de incorporación. Selecciona Copy para cada valor; no necesitas abrir Settings > App Settings.
3. Usa la clave de API copiada como BRAZE_API_KEY y el punto final de SDK como BRAZE_API_URL en tus variables de entorno de Shopify (Paso 2).

Después de conectar la tienda, puedes renombrar la aplicación de sitio web seleccionada en Settings > App Settings. No puedes eliminar la aplicación mientras esté conectada a tu integración de Shopify.

Advertencia

Usa la clave de API de la aplicación de sitio web que seleccionaste durante la incorporación. Si tu entorno Hydrogen usa una clave de API diferente a la conectada a tu integración de Shopify, Braze puede crear usuarios duplicados y los métodos del SDK pueden no funcionar como se espera.

Paso 2: Agrega el subdominio y las variables de entorno

1. Configura tu subdominio de Shopify para redirigir el tráfico de tu tienda en línea a Hydrogen.
2. Agrega un URI de devolución de llamada para el inicio de sesión. (El URI se añadirá automáticamente cuando se agregue el dominio.)
3. Configura tus variables de entorno de Shopify:
   • Crea dos variables de entorno usando la clave de API y el punto final de SDK que copiaste durante la incorporación de configuración personalizada en el Paso 1.
   • BRAZE_API_KEY
   • BRAZE_API_URL

Paso 3: Habilita el seguimiento en el sitio

El primer paso es inicializar el SDK web de Braze. Recomendamos hacerlo instalando nuestro paquete NPM:

1
2
3

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

Importante

La versión mínima compatible del SDK web de Braze es la 5.4.0. Para integraciones personalizadas de Shopify (incluidos los escaparates headless), recibes notificaciones cuando hay nuevas versiones del SDK disponibles, pero gestionas las actualizaciones de tu lado, actualizando tanto el código de tu escaparate como la versión del SDK en la configuración de integración.

Luego, incluye esta configuración como una clave de nivel superior en tu archivo vite.config.js:

1
2
3

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

Después de instalar el paquete NPM, debes inicializar el SDK dentro de un hook useEffect en el componente Layout. Dependiendo de tu versión de Hydrogen, este componente puede estar ubicado en el archivo root.jsx o 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 (...);
}

Los valores data.brazeApiKey y data.brazeApiUrl deben incluirse en el loader del componente usando las variables de entorno creadas en el Paso 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

Las políticas de seguridad de contenido (generalmente ubicadas en el archivo de Hydrogen entry.server.jsx) pueden afectar la funcionalidad de los scripts de Braze tanto en entornos locales como de producción. Te sugerimos probar a través de compilaciones de vista previa enviadas a Shopify a través de Oxygen o despliegues personalizados. Si encuentras problemas, tendrás que configurar tu CSP para permitir que nuestro JavaScript funcione.

Paso 4: Agrega un evento de inicio de sesión de cuenta de Shopify

Haz seguimiento de cuándo un comprador inicia sesión en su cuenta y sincroniza su información de usuario con Braze. Esto incluye llamar a nuestro método changeUser para identificar a los clientes con un ID externo de Braze.

Nota

Actualmente no tenemos orientación para admitir un ID externo de Braze personalizado. Si necesitas esto para tu integración ahora, contacta a tu administrador de éxito de cliente.

Antes de empezar, asegúrate de haber configurado los URI de devolución de llamada para que el inicio de sesión del cliente funcione dentro de Hydrogen. Para más información, consulta Usar la API de cuenta de cliente con Hydrogen.

1. Después de configurar los URI de devolución de llamada, define una función para llamar al SDK de Braze. Crea un nuevo archivo (como Tracking.jsx) e impórtalo desde tus 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. En el mismo hook useEffect que inicializa el SDK de Braze, agrega la llamada a esta función:

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. Obtén la dirección de correo electrónico y el número de teléfono del cliente en tu consulta GraphQL de la API de cliente, ubicada en el archivo 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. Finalmente, carga los datos del cliente en tu función 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,
    },
  };
}

Paso 5: Agrega seguimiento para los eventos Product Viewed y Cart Updated

Eventos Product Viewed

1. Agrega esta función a tu archivo 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 llamar a la función anterior cada vez que un usuario visita una página de producto, agrega un hook useEffect al componente Product dentro del archivo 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. Agrega el valor para “storefrontUrl” (ya que no está en el loader del componente por defecto):

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 integración, el alias de usuario debe utilizar el siguiente formato para que Braze pueda asociar los webhooks con el perfil de usuario correcto:

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

1. Define funciones para hacer seguimiento del evento cart_updated y establecer el token del carrito:

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. Devuelve el objeto cart desde la acción del fetcher para que Braze pueda acceder a sus propiedades, yendo a tu archivo app/routes/cart.jsx y agregando lo siguiente a la función 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 más información sobre los fetchers de Remix, consulta useFetcher.

3. Las tiendas Hydrogen generalmente definen un componente CartForm que gestiona el estado del objeto del carrito, el cual se usa al agregar, eliminar y cambiar la cantidad de artículos en un carrito. Agrega otro hook useEffect en el componente AddToCartButton que llamará a la función trackCartUpdated cada vez que el estado del fetcher del formulario cambie (cada vez que se actualice el carrito del usuario):

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. Usa el mismo fetcherKey para las acciones encargadas de actualizar un producto existente en tu carrito. Agrega lo siguiente a los componentes CartLineRemoveButton y CartLineUpdateButton (ubicados por defecto en el archivo 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 la integración de Braze con Shopify

Paso 1: Conecta tu tienda Shopify

Ve a la página del partner de Shopify para iniciar la configuración. Primero, selecciona Begin Setup para instalar la aplicación de Braze desde la Shopify App Store. Sigue los pasos guiados para completar el proceso de instalación.

Paso 2: Habilitar los SDK de Braze

Para tiendas Shopify Hydrogen o headless, selecciona la opción Custom setup.

La configuración personalizada incluye un selector de aplicación web. Selecciona o crea la aplicación que alimenta tu tienda, luego copia la clave de API y el punto final de SDK que se muestran en el paso de incorporación. Para más detalles, consulta Paso 1: Seleccionar una aplicación web y copiar las credenciales del SDK.

Antes de continuar con el proceso de incorporación, confirma que has añadido el SDK de Braze a tu sitio web de Shopify utilizando esas credenciales.

Paso 3: Rastrear datos de Shopify

Mejora tu integración añadiendo más eventos y atributos de Shopify, que serán impulsados por webhooks de Shopify. Para información detallada sobre los datos rastreados a través de esta integración, consulta Características de datos de Shopify.

Paso 4: Relleno histórico (opcional)

A través de la configuración personalizada, puedes incluir opcionalmente la misma carga de datos históricos de Shopify que la integración estándar: eventos de pedidos de los últimos 90 días y perfiles de usuario del último año, contados desde la fecha en que completes tu integración. Para incluir esta carga de datos inicial, selecciona la casilla de verificación de la opción de carga de datos inicial.

Si prefieres realizar el relleno más tarde, puedes completar la configuración inicial ahora y volver a este paso en otro momento.

Para la lista completa de datos en la carga inicial, el comportamiento de informes de ingresos y la monitorización de la sincronización, consulta Relleno histórico.

Paso 5: Configuración de seguimiento de datos personalizados (avanzado)

Con los SDK de Braze, puedes rastrear eventos personalizados o atributos personalizados que van más allá de los datos admitidos para esta integración. Los eventos personalizados capturan interacciones únicas en tu tienda, como:

El SDK debe estar inicializado (escuchando actividad) en el dispositivo del usuario para registrar eventos o atributos personalizados. Para obtener más información sobre el registro de datos personalizados, consulta User object y logCustomEvent.

Paso 6: Configurar cómo gestionas los usuarios (opcional)

Selecciona tu tipo de external_id en el menú desplegable.

Importante

Usar una dirección de correo electrónico o una dirección de correo electrónico con hash como tu ID externo de Braze puede ayudar a simplificar la gestión de identidad en tus orígenes de datos. Sin embargo, es importante considerar los posibles riesgos para la privacidad del usuario y la seguridad de los datos.

• Información predecible: Las direcciones de correo electrónico son fácilmente predecibles, lo que las hace vulnerables a ataques.
• Riesgo de explotación: Si un usuario malintencionado modifica su navegador web para enviar la dirección de correo electrónico de otra persona como su ID externo, podría acceder potencialmente a mensajes sensibles o información de la cuenta.

De forma predeterminada, Braze convierte automáticamente los correos electrónicos de Shopify a minúsculas antes de usarlos como ID externo. Si estás usando el correo electrónico o el correo electrónico con hash como tu ID externo, confirma que tus direcciones de correo electrónico también se conviertan a minúsculas antes de asignarlas como tu ID externo o antes de aplicarles el hash desde otros orígenes de datos. Esto ayuda a prevenir discrepancias en los ID externos y evitar la creación de perfiles de usuario duplicados en Braze.

Nota

Los siguientes pasos dependen de tu selección de ID externo:

• Si seleccionaste un tipo de ID externo personalizado: Completa los pasos 6.1 a 6.3 para configurar tu ID externo personalizado.
• Si seleccionaste ID de cliente de Shopify, correo electrónico o correo electrónico con hash: Salta los pasos 6.1 a 6.3 y continúa directamente al paso 6.4.

Paso 6.1: Crear el metafield braze.external_id

1. En tu panel de administración de Shopify, ve a Settings > Metafields.
2. Selecciona Customers > Add definition.
3. En Namespace and key, introduce braze.external_id.
4. En Type, selecciona ID Type.

Después de crear el metafield, rellénalo para tus clientes. Recomendamos los siguientes enfoques:

• Escuchar webhooks de creación de clientes: Configura un webhook para escuchar eventos customer/create. Esto te permite escribir el metafield cuando se crea un nuevo cliente.
• Rellenar clientes existentes: Usa la Admin API o la Customer API para rellenar el metafield de los clientes creados previamente.

Paso 6.2: Crear un endpoint para obtener tu ID externo

Debes crear un endpoint público al que Braze pueda llamar para obtener el ID externo. Esto permite que Braze obtenga el ID en escenarios en los que Shopify no puede proporcionar el metafield braze.external_id directamente.

Especificaciones del endpoint

Método: GET

Braze envía los siguientes parámetros a tu endpoint:

Ejemplo de endpoint

1

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

Respuesta esperada

Braze espera un código de estado 200 que devuelva el JSON del ID externo:

1
2
3

{
  "external_id": "my_external_id"
}

Validación

Es fundamental validar que el shopify_customer_id y la email_address (si está presente) coincidan con los valores del cliente en Shopify. Puedes usar la Shopify Admin API o la Customer API para validar estos parámetros y obtener el metafield braze.external_id correcto.

Comportamiento en caso de fallo y fusión

Cualquier código de estado distinto de 200 se considera un fallo.

• Implicaciones de la fusión: Si el endpoint falla (devuelve un código distinto de 200 o se agota el tiempo de espera), Braze no puede recuperar el ID externo. En consecuencia, la fusión entre el usuario de Shopify y el perfil de usuario de Braze no se produce en ese momento.
• Lógica de reintentos: Braze puede intentar reintentos de red inmediatos estándar, pero si el fallo persiste, la fusión se aplaza hasta el siguiente evento que cumpla las condiciones (por ejemplo, la próxima vez que el usuario actualice su perfil o complete un proceso de pago).
• Compatibilidad: Para facilitar la fusión oportuna de usuarios, asegúrate de que tu endpoint tenga alta disponibilidad y gestione correctamente el campo opcional email_address.

Paso 6.3: Ingresar tu ID externo

Repite el Paso 6 e ingresa la URL de tu endpoint después de seleccionar ID externo personalizado como tu tipo de ID externo de Braze.

Consideraciones

• Si tu ID externo no se genera cuando Braze envía una solicitud a tu endpoint, la integración usará de forma predeterminada el ID de cliente de Shopify cuando se llame a la función changeUser. Este paso es crucial para fusionar el perfil de usuario anónimo con el perfil de usuario identificado. Como resultado, puede haber un período temporal durante el cual existan diferentes tipos de ID externos dentro de tu espacio de trabajo.
• Cuando el ID externo esté disponible en el metacampo braze.external_id, la integración priorizará y asignará este ID externo.
  • Si el ID de cliente de Shopify se estableció previamente como el ID externo de Braze, se reemplazará con el valor del metacampo braze.external_id.

Paso 6.4: Recopilar adhesiones voluntarias de correo electrónico o SMS desde Shopify (opcional)

Si usas los canales de correo electrónico o SMS, puedes sincronizar los estados de adhesión voluntaria de marketing por correo electrónico y SMS desde Shopify en Braze.

• correo electrónico
• doble adhesión voluntaria por sms

Si sincronizas las adhesiones voluntarias de marketing por correo electrónico desde Shopify, Braze crea automáticamente un grupo de suscripción de correo electrónico para todos los usuarios asociados con esa tienda específica. Necesitas crear un nombre único para este grupo de suscripción.

Nota

Como se menciona en el resumen de Shopify, si quieres utilizar un formulario de captura de terceros, tus desarrolladores necesitan integrar el código del SDK de Braze. Esto te permitirá capturar la dirección de correo electrónico y el estado de suscripción global de correo electrónico a partir de los envíos de formularios. Específicamente, necesitas implementar y probar estos métodos en tu archivo theme.liquid:

• setEmail: establece la dirección de correo electrónico en el perfil de usuario
• setEmailNotificationSubscriptionType: actualiza el estado de suscripción global de correo electrónico

Usa la doble adhesión voluntaria por SMS para enviar tu texto de confirmación con tu marca a través de Braze en lugar del correo electrónico de confirmación de Shopify. Para activar la doble adhesión voluntaria por SMS:

1. En el panel de administración de Shopify, ve a Configuración > Notificaciones > Notificaciones de clientes.
2. Desactiva la doble adhesión voluntaria de marketing para SMS.
3. Configura el SMS de checkout como adhesión voluntaria simple.
4. En la configuración de SMS de Braze, selecciona Usar doble adhesión voluntaria por SMS de Braze.

Para más información sobre la doble adhesión voluntaria por SMS de Braze y el flujo de suscriptores, consulta Resumen de Shopify.

Paso 7: Sincronizar productos (opcional)

Puedes sincronizar todos los productos de tu tienda Shopify con un catálogo de Braze para una personalización más profunda de los mensajes. Las actualizaciones automáticas ocurren casi en tiempo real, por lo que tu catálogo siempre refleja los detalles más recientes de los productos. Para obtener más información, consulta Sincronización de productos de Shopify.

Paso 8: Activar canales

Para activar In-App Messages, Banners y conmutadores de características usando la integración directa de Shopify, añade cada canal a tu SDK. Sigue los enlaces de documentación proporcionados para cada canal:

• In-App Messages: Para habilitar In-App Messages para casos de uso de formularios de captación de leads, consulta In-App Messages.
• Banners: Para habilitar Banners para casos de uso de personalización de la tienda Shopify, consulta Banners.
• Conmutadores de características: Para habilitar conmutadores de características para casos de uso de experimentación en la tienda Shopify, consulta Conmutadores de características.

Paso 9: Finalizar la configuración

Después de haber completado todos los pasos, selecciona Finish Setup para volver a la página del partner. Luego, habilita la inserción de la aplicación Braze en tu página de administración de Shopify como indica el banner que se muestra.

Código de ejemplo

shopify-hydrogen-example es una aplicación Hydrogen de ejemplo que contiene todo el código cubierto en los pasos anteriores.