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:

Inicializa y carga 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 tienda Hydrogen, conecta tu tienda Shopify e inicia la incorporación de la configuración personalizada. Si aún no has conectado tu tienda, completa Conecta tu tienda Shopify y luego continúa con Habilitar los SDK de Braze y selecciona Configuración personalizada.

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

1. Selecciona una aplicación de sitio web existente o crea una nueva. Puedes ponerle a la aplicación cualquier nombre 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 Copiar para cada valor; no necesitas abrir Configuración > Configuración de la aplicación.
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 cambiar el nombre de la aplicación de sitio web seleccionada en Configuración > Configuración de la aplicación. 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 de Hydrogen usa una clave de API distinta de la conectada a tu integración de Shopify, Braze podría crear usuarios duplicados y es posible que los métodos del SDK no funcionen como se espera.

Paso 2: Añade el subdominio y las variables de entorno

1. Configura tu subdominio de Shopify para redirigir el tráfico de tu tienda online a Hydrogen.
2. Añade un URI de devolución de llamada para el inicio de sesión. (El URI se añadirá automáticamente cuando se añada el dominio).
3. Configura tus variables de entorno de Shopify:
   • Crea dos variables de entorno con la clave de API y el punto final de SDK que copiaste durante la incorporación de la 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. Te 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. En las integraciones personalizadas de Shopify (incluidas las tiendas headless), recibes notificaciones cuando hay nuevas versiones del SDK disponibles, pero tú gestionas las actualizaciones por tu cuenta, actualizando tanto el código de tu tienda como la versión del SDK en la configuración de la integración.

Después, incluye esta configuración como 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. Según tu versión de Hydrogen, este componente puede estar en el archivo root.jsx o en 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 (normalmente ubicadas en el archivo entry.server.jsx de Hydrogen) pueden afectar al funcionamiento de los scripts de Braze tanto en entornos locales como de producción. Te recomendamos hacer pruebas mediante compilaciones de vista previa enviadas a Shopify a través de Oxygen o implementaciones personalizadas. Si encuentras problemas, tendrás que configurar tu CSP para permitir que nuestro JavaScript funcione.

Paso 4: Añade un evento de inicio de sesión en la cuenta de Shopify

Haz un 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 disponemos de instrucciones para admitir un ID externo de Braze personalizado. Si lo necesitas ahora para tu integración, ponte en contacto con 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 en Hydrogen. Para más información, consulta Uso de la API de cuentas 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 archivo nuevo (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, añade 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 clientes, 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. Por último, 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: Añade el seguimiento de los eventos de producto visto y carrito actualizado

Eventos de producto visto

1. Añade 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 visite una página de producto, añade 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. Añade el valor de “storefrontUrl” (porque no está en el loader del componente de forma predeterminada):

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

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 el 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. Para ello, ve a tu archivo app/routes/cart.jsx y añade 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 suelen definir un componente CartForm que gestiona el estado del objeto del carrito, que se usa al añadir, eliminar y cambiar la cantidad de artículos de un carrito. Añade otro hook useEffect en el componente AddToCartButton que llame a la función trackCartUpdated cada vez que cambie el estado del fetcher del formulario (es decir, 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 de tu carrito. Añade lo siguiente a los componentes CartLineRemoveButton y CartLineUpdateButton (ubicados de forma predeterminada 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 comenzar la configuración. Primero, selecciona Comenzar configuración 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: Habilita los SDK de Braze

Para tiendas Shopify Hydrogen o headless, selecciona la opción Configuración personalizada.

La configuración personalizada incluye un selector de aplicaciones de sitio web. Selecciona o crea la aplicación que impulsa tu tienda online y, a continuación, 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: Selecciona una aplicación de sitio web y copia 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 con esas credenciales.

Paso 3: Haz un seguimiento de los datos de Shopify

Mejora tu integración añadiendo más eventos y atributos de Shopify, que funcionarán con los webhooks de Shopify. Para obtener información detallada sobre los datos de los que se hace un seguimiento con esta integración, consulta Características de los datos de Shopify.

Paso 4: Carga retroactiva de datos históricos (opcional)

Con la configuración personalizada, puedes incluir opcionalmente la misma carga de datos históricos de Shopify que la integración estándar.

Selecciona Activar la carga retroactiva histórica y, a continuación, elige un intervalo de fechas para los pedidos (Últimos 90 días, Último año o Últimos 2 años) y para los perfiles de clientes (Último año, Últimos 2 años o Todo el tiempo). Estas selecciones no se pueden cambiar una vez completada la configuración.

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

Para ver la lista completa de datos de la carga inicial, el comportamiento de los informes de ingresos y cómo supervisar la sincronización, consulta Carga retroactiva histórica.

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

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

El SDK debe estar inicializado (a la escucha de 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 Objeto de usuario y logCustomEvent.

Paso 6: Configura cómo administras a los usuarios (opcional)

Selecciona tu tipo de external_id en el desplegable.

Importante

Usar una dirección de correo electrónico o una dirección de correo electrónico con hash como ID externo de Braze puede ayudarte a simplificar la administración de identidades en todos tus orígenes de datos. Sin embargo, es importante tener en cuenta los posibles riesgos para la privacidad de los usuarios y la seguridad de los datos.

• Información fácil de adivinar: Las direcciones de correo electrónico son fáciles de adivinar, 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 a mensajes confidenciales o a información de la cuenta.

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

Nota

Los siguientes pasos dependen del ID externo que hayas seleccionado:

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

Paso 6.1: Crea el metacampo 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.

Una vez creado el metacampo, rellénalo para tus clientes. Te recomendamos los siguientes enfoques:

• Escucha los webhooks de creación de clientes: Configura un webhook para escuchar los eventos customer/create. Esto te permite escribir el metacampo cuando se crea un nuevo cliente.
• Carga retroactiva de clientes existentes: Usa la Admin API o la Customer API para rellenar retroactivamente el metacampo de los clientes creados anteriormente.

Paso 6.2: Crea un endpoint para recuperar tu ID externo

Debes crear un endpoint público al que Braze pueda llamar para recuperar el ID externo. Esto permite a Braze obtener el ID en situaciones en las que Shopify no puede proporcionar directamente el metacampo braze.external_id.

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 shopify_customer_id y email_address (si está presente) coinciden con los valores del cliente en Shopify. Puedes usar la Shopify Admin API o la Customer API para validar estos parámetros y recuperar el metacampo braze.external_id correcto.

Comportamiento en caso de error y fusión

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

• 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: Introduce tu ID externo

Repite el Paso 6 e introduce la URL de tu endpoint después de seleccionar el ID externo personalizado como 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: Recopila tus adhesiones voluntarias de correo electrónico o SMS desde Shopify (opcional)

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

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

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 a esa tienda específica. Tienes que 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 mensaje de confirmación personalizado 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 la página 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 del 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.

Si envías mensajes de WhatsApp a través de Braze, también puedes sincronizar las adhesiones voluntarias de marketing por WhatsApp desde Shopify. Selecciona Recopilar suscriptores de WhatsApp y, a continuación, selecciona los grupos de suscripción de WhatsApp con los que quieres sincronizar.

Importante

Tu espacio de trabajo necesita una cuenta de WhatsApp Business conectada para tener grupos de suscripción de WhatsApp. Conecta una en Partners tecnológicos > WhatsApp.

Braze solo sincroniza el consentimiento de WhatsApp que Shopify almacena para un cliente. Una adhesión voluntaria por SMS o correo electrónico no suscribe a un cliente a WhatsApp, y no existe la doble adhesión voluntaria para WhatsApp. Para más información, consulta Adhesiones voluntarias de marketing por WhatsApp.

Paso 7: Sincroniza los productos (opcional)

Puedes sincronizar todos los productos de tu tienda Shopify con un catálogo de Braze para personalizar aún más tus mensajes. Las actualizaciones automáticas se producen 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: Activa los canales

Para activar los mensajes dentro de la aplicación, los banners y los conmutadores de características mediante la integración directa con Shopify, añade cada canal a tu SDK. Sigue los enlaces a la documentación de cada canal:

• Mensajes dentro de la aplicación: Para habilitar los mensajes dentro de la aplicación en casos de uso de formularios de captura de clientes potenciales, consulta Mensajes dentro de la aplicación.
• Banners: Para habilitar los banners en casos de uso de personalización de la tienda online de Shopify, consulta Banners.
• Conmutadores de características: Para habilitar los conmutadores de características en casos de uso de experimentación en la tienda online de Shopify, consulta Conmutadores de características.

Paso 9: Finaliza la configuración

Cuando hayas completado todos los pasos, selecciona Finalizar configuración para volver a la página del partner. Después, habilita la inserción de la aplicación de Braze en tu página de administración de Shopify, tal y como indica el banner que aparece.

Código de ejemplo

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