Descripción general del servicio de Segmentación por clientes leales

En esta guía, se describe cómo usar el servicio de Segmentación por clientes leales en la API de Merchant. Este servicio permite a los comercios administrar los datos de lealtad de los clientes, como los identificadores de usuario y la información de niveles, para la personalización orgánica en la Búsqueda de Google, sin necesidad de tener una cuenta activa de Google Ads.

Descripción general

Usa el servicio de Segmentación por clientes de lealtad para subir datos de lealtad, que luego se usan para proporcionar funciones de personalización de lealtad orgánicas en la Búsqueda de Google, como mostrar precios específicos para miembros. Utilizas el método personalizado ManageLoyaltyCustomerMatch para asociar a tus clientes con los niveles del programa de lealtad, lo que te permite insertar, actualizar o quitar su estado de lealtad según los identificadores de usuario.

Conceptos clave

  • Interfaz unificada: Es un extremo único para agregar, actualizar o quitar detalles del nivel de lealtad del cliente.
  • Privacidad ante todo: Para proteger la privacidad del usuario y evitar la exploración no autorizada de cuentas, la API no admite operaciones GET ni LIST, lo que garantiza que los datos se administren sin recuperación ni auditoría.
  • Identificación flexible: Haz coincidir a los usuarios con al menos un identificador válido, como una dirección de correo electrónico, una dirección física o un número de teléfono.
  • Tratamiento basado en el consentimiento: El servicio almacena y usa los datos del cliente solo cuando el usuario final otorgó el consentimiento necesario a Google. Para proteger y evitar la detección de la existencia de la cuenta o el estado de consentimiento, el servicio devuelve un éxito silencioso si no se encuentra una coincidencia o no se otorga el consentimiento.

Requisitos previos

Sigue estos requisitos para usar el servicio de Segmentación por clientes leales:

  • Configuración de la cuenta: Asegúrate de tener una cuenta activa de Merchant Center. No es necesario que crees una cuenta de Google Ads para usar el servicio de Segmentación por clientes leales.
  • Configuración del programa de lealtad: Habilita el programa de lealtad en tu cuenta de Merchant Center y asegúrate de haber definido los niveles de lealtad.
  • Orden de los niveles: Ten en cuenta el orden en el que se definen tus niveles de lealtad en la IU de Merchant Center. La API usa esta secuencia exacta para su asignación de enumeración.

Método: ManageLoyaltyCustomerMatch

El método ManageLoyaltyCustomerMatch funciona como la interfaz central para administrar las asociaciones de lealtad del cliente. Según la entrada proporcionada, el servicio determina automáticamente si se debe insertar, actualizar o quitar el estado del nivel de lealtad de un cliente. La operación es idempotente: Las solicitudes idénticas repetidas tienen el mismo efecto que una sola solicitud.

En la siguiente solicitud, se muestra cómo administrar las asociaciones de lealtad del cliente a través de la API:

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

Esta solicitud define los siguientes parámetros de ruta obligatorios:

  • api_version: Es la versión de la API, como v1.
  • account_id: Es el ID de la cuenta de Merchant Center.

Incluye un objeto loyaltyCustomer en el cuerpo de la solicitud.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

Campos de loyaltyCustomer

  • userIdentifier: Es el conjunto de identificadores que se usan para correlacionar al cliente. Se debe proporcionar y validar al menos un campo dentro de userIdentifier.
  • loyaltyTier: Es el nivel de lealtad que se asociará con el cliente. Se asigna al orden del nivel en la configuración de Merchant Center. Para obtener más información, consulta Información sobre la asignación de loyaltyTier. Usa NON_MEMBER para quitar una asociación existente.
  • pointBalance: Es el saldo de puntos actual del cliente.

Campos userIdentifier

Se debe proporcionar, al menos, uno de los siguientes campos:

  • emailAddress: Es la dirección de correo electrónico del cliente.
  • address: Es la dirección física del cliente. Se requiere el parámetro PostalCode.
  • phoneNumber: Es el número de teléfono del cliente. Se recomienda el formato E.164.

Información sobre el mapeo de loyaltyTier

La API no usa los nombres personalizados. Los valores de enumeración loyaltyTier (de TIER1 a TIER7) son etiquetas semánticas. No usan los nombres personalizados (por ejemplo, "Recompensas Gold") ni las etiquetas personalizadas (por ejemplo, "nivel_gold") que asignaste en la IU de Merchant Center. En cambio, se asignan estrictamente al orden en el que definiste tus niveles en la configuración del programa de lealtad en Merchant Center:

  • TIER1: Corresponde al primer nivel que se indica en la configuración de tu programa de lealtad de Merchant Center.
  • TIER2: Corresponde al segundo nivel que se indica en la configuración de tu programa de lealtad de Merchant Center.
  • TIER3 a TIER7: Corresponden a los niveles tercero a séptimo que se indican en la configuración de tu programa de lealtad de Merchant Center.

Ejemplo:

Si tu programa de lealtad de Merchant Center tiene niveles definidos en este orden:

  1. Nombre del nivel: "Silver Status", etiqueta del nivel: "silver"
  2. Nombre del nivel: "Miembro Gold", etiqueta del nivel: "gold"
  3. Nombre del nivel: "Platinum Elite", etiqueta del nivel: "platinum"

Luego, en las llamadas a la API de accounts.loyaltyCustomers.manage, haz lo siguiente:

  • Para asignar un cliente al "Estado Silver", debes usar loyaltyTier: TIER1.
  • Para asignar un cliente a "Miembro Gold", debes usar loyaltyTier: TIER2.
  • Para asignar un cliente a "Platinum Elite", debes usar loyaltyTier: TIER3.

Valores de enumeración de LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (se usa para indicar la eliminación de la asociación de lealtad del cliente)

Información sobre el cuerpo de la respuesta de ManageLoyaltyCustomerMatch

El método ManageLoyaltyCustomerMatch devuelve un objeto ManageLoyaltyCustomerMatchResponse:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Consideraciones importantes sobre las posibles respuestas:

  • Upsert exitoso (datos almacenados): Para almacenar o actualizar correctamente la asociación del nivel de lealtad de un cliente, se deben cumplir las siguientes condiciones:

    • correlacionas a un usuario de Google con el userIdentifier proporcionado
    • Estableces el loyaltyTier en la solicitud en un valor válido que no sea NON_MEMBER.
    • el usuario correlacionado dio su consentimiento para el uso de datos de lealtad

La respuesta contiene el objeto loyaltyCustomer de tu solicitud, lo que indica que los datos se procesaron y almacenaron correctamente:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Borrado exitoso: Para quitar correctamente cualquier asociación de lealtad existente del cliente con este comercio, se deben cumplir las siguientes condiciones:
    • correlacionas a un usuario de Google con el userIdentifier proporcionado
    • Establece el loyaltyTier en la solicitud como NON_MEMBER.

La respuesta es un objeto JSON vacío:

{}
  • Sin coincidencia o sin consentimiento (éxito silencioso): Si el userIdentifier proporcionado no coincide con una Cuenta de Google o si el usuario coincidente no dio su consentimiento para el uso de los datos de lealtad, la API devuelve un estado HTTP 200 OK con un objeto JSON vacío: {}. Esto sucede tanto para los intentos de inserción y actualización como para los de eliminación.

Ejemplos

TIER1 corresponde al primer nivel definido del comercio, el que se llama "Básico", y TIER2 a su segundo nivel, "Premium".

Para agregar un cliente a TIER2 o actualizar su estado con una dirección de correo electrónico, envía la siguiente solicitud:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Cuando se encuentra una coincidencia para un usuario y este da su consentimiento, la API devuelve la siguiente respuesta:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Cuando no hay coincidencias o el usuario no dio su consentimiento, la API devuelve la siguiente respuesta:

{}

Para quitar la asociación de lealtad de un cliente con un número de teléfono, envía la siguiente solicitud:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Independientemente de si existía un registro, la API devuelve la siguiente respuesta de éxito:

{}

Para agregar o actualizar un cliente con varios identificadores, envía la siguiente solicitud:

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

La respuesta es similar al primer ejemplo, según la coincidencia y el consentimiento.

Manejo de errores

La API usa códigos HTTP estándar. Entre las cadenas de error comunes, se incluyen las siguientes:

Código HTTP Cadena de error Descripción
400 INVALID_ARGUMENT Faltan user_identifier o loyalty_tier, o el identificador está vacío.
401 UNAUTHENTICATED Faltan credenciales o no son válidas.
403 PERMISSION_DENIED El usuario autenticado no tiene acceso a la cuenta de Merchant Center especificada.
404 NOT_FOUND La etiqueta de nivel de lealtad especificada no existe en tu configuración.
412 FAILED_PRECONDITION No configuraste un programa de lealtad en tu cuenta.
429 RESOURCE_EXHAUSTED Se alcanzó el límite de cuota.

Ejemplos de errores

Ejemplo de 404 NOT_FOUND:

Cualquier solicitud válida a un ID de cuenta que no tenga configurado un programa de lealtad.

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {account_id}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{account_id}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

Motivo: La cuenta de comerciante en la ruta de acceso no tiene un programa de lealtad activo.

Ejemplos de 400 INVALID_ARGUMENT:

Se produce un error si la solicitud contiene un valor no válido para el campo loyaltyTier:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

Motivo: TIER11 no es un valor de enumeración válido para loyaltyTier. El mismo error puede ocurrir cuando intentas especificar TIER2 cuando solo hay un nivel disponible.

Se produce un error si falta el campo loyaltyTier obligatorio en el cuerpo de la solicitud:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Motivo: El campo loyaltyTier es obligatorio.

Se produce un error si un identificador de dirección está incompleto, por ejemplo, cuando falta el campo postalCode:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motivo: Se proporcionó una dirección, pero falta el campo obligatorio postalCode, por lo que no se considera un identificador válido.

Se produce un error si solicitas un índice de nivel que está fuera de los límites del programa configurado:

Situación: El comercio solo tiene un nivel configurado en Merchant Center.

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motivo: Se solicitó TIER2, pero el programa de lealtad vinculado a la cuenta no tiene un segundo nivel definido.

Se produce un error si la solicitud contiene un emailAddress con formato incorrecto:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

Motivo: El formato de la dirección de correo electrónico no es válido.

Se produce un error si el objeto userIdentifier está vacío:

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

La API devuelve la siguiente respuesta de error:

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

Motivo: El objeto userIdentifier está presente, pero no contiene campos de identificador reales.

Nota sobre la validación de identificadores:

  • La API realiza verificaciones de formato básicas en los identificadores (por ejemplo, estructura de correo electrónico, presencia de postalCode en las direcciones).
  • Sin embargo, es posible que algunos identificadores que pasan las verificaciones iniciales no coincidan con ninguna cuenta de usuario de Google o no estén en un formato que reconozca el sistema de correlación de backend. En esos casos, recibirás la respuesta silenciosa de éxito vacía {} con el estado HTTP 200 OK.

Prácticas recomendadas

Sigue estas prácticas recomendadas para optimizar tu integración.

  • Para la integración a gran escala: Debido a que la API opera por solicitud, se requiere paralelismo del lado del cliente para lograr la capacidad de procesamiento necesaria para los conjuntos de datos grandes. Debes diseñar tu integración para administrar varias solicitudes simultáneas. Para obtener orientación sobre cómo estructurar tu implementación para controlar volúmenes más altos a través de la paralelización, consulta nuestra guía sobre cómo enviar varias solicitudes.

  • Administración de cuotas: La cuota predeterminada es de 1,000,000 de solicitudes por día y 10,000 solicitudes por minuto. Para saber cómo supervisar y verificar tus cuotas, consulta Cuotas y límites.

  • Prioriza la dirección de correo electrónico: Siempre que sea posible, incluye el emailAddress del cliente en el userIdentifier. En general, las direcciones de correo electrónico son el identificador más preciso y confiable para correlacionar a los usuarios con sus Cuentas de Google.

  • Controla las respuestas vacías: Diseña tu aplicación para que interprete correctamente las respuestas {} vacías como un éxito, y comprende que significa que los datos no se almacenaron por motivos de privacidad (no hay coincidencias o no se otorgó el consentimiento). No vuelvas a intentar la solicitud.

  • Verifica el orden de los niveles: Siempre confirma el orden de tus niveles de lealtad en la IU de Merchant Center para asegurarte de usar los valores de enumeración correctos de TIER1 a TIER7 en tus llamadas a la API. Esta asignación se basa en el orden definido en la IU, no en sus nombres.

  • Supervisa los errores: Registra y supervisa las respuestas de la API, y presta atención a los errores 4xx para detectar problemas de integración, en especial los errores 404, que pueden indicar una falta de coincidencia en la comprensión del nivel.