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 de lealtad en la API de Merchant. Este servicio permite que los comercios y los proveedores de lealtad externos que actúan en nombre de los comercios administren los datos de lealtad de los clientes, como los identificadores de usuario y la información de nivel, para la personalización orgánica en la Búsqueda de Google, sin necesidad de tener una cuenta de Google Ads activa.

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ánica en la Búsqueda de Google, como mostrar precios específicos para miembros. Usa 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.
  • Diseño que prioriza la privacidad: Para proteger la privacidad del usuario y evitar el sondeo de cuentas no autorizado, 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: Segmenta por 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.
  • Procesamiento 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 realiza una coincidencia o no se otorga el consentimiento.

Requisitos previos

Sigue estos requisitos para usar el Servicio de Segmentación por Clientes de Lealtad:

  • Configuración de la cuenta: Asegúrate de tener una cuenta de Merchant Center activa (o acceso autorizado a la cuenta del comercio si eres un proveedor de lealtad externo). No necesitas crear una cuenta de Google Ads para usar el servicio de Segmentación por clientes de lealtad.
  • 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.
  • Ten en cuenta el 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 enum.

Método: ManageLoyaltyCustomerMatch

El método ManageLoyaltyCustomerMatch funciona como la interfaz central para administrar las asociaciones de lealtad de los clientes. 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 de los clientes 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 utilizan para encontrar coincidencias con el cliente. Se debe proporcionar al menos un campo válido 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

Proporciona, 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. El código postal es obligatorio.
  • phoneNumber: Es el número de teléfono del cliente. Se recomienda el formato E.164.

Información sobre la asignación de loyaltyTier

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

  • TIER1: Corresponde al primer nivel que aparece en la configuración del programa de lealtad de Merchant Center.
  • TIER2: Corresponde al segundo nivel que aparece en la configuración del programa de lealtad de Merchant Center.
  • TIER3 a TIER7: Corresponden a los niveles del tercero al séptimo que se indican en la configuración del 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 de nivel: "silver"
  2. Nombre del nivel: "Miembro Gold", etiqueta de nivel: "gold"
  3. Nombre del nivel: "Platinum Elite", etiqueta de nivel: "platinum"

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

  • Para asignar un cliente a "Silver Status", 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 enum de LoyaltyTier

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

Comprende el cuerpo de la respuesta de ManageLoyaltyCustomerMatch

El método ManageLoyaltyCustomerMatch devuelve un objeto ManageLoyaltyCustomerMatchResponse:

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

Consideraciones importantes para las respuestas

  • Actualización o inserción exitosa (datos almacenados): Para almacenar o actualizar correctamente la asociación de nivel de lealtad de un cliente, cumple con las siguientes condiciones:

    • coincides con 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 coincidente dio su consentimiento para el uso de los datos de lealtad.

La respuesta contiene el objeto loyaltyCustomer de tu solicitud, lo que indica que el servicio procesó y almacenó los datos de forma correcta:

{
  "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:
    • coincides con un usuario de Google con el userIdentifier proporcionado
    • estableces el loyaltyTier en la solicitud como NON_MEMBER

La respuesta es un objeto JSON vacío:

{}
  • No hay coincidencia ni 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 actualización o inserción como para los de eliminación.

Ejemplos

TIER1 corresponde al primer nivel definido (por ejemplo, 'Basic') y TIER2 corresponde al segundo nivel (por ejemplo, '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 un usuario coincide correctamente y dio 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 a la del primer ejemplo, según la coincidencia y el consentimiento.

Manejo de errores

La API usa códigos HTTP estándar. Estas son algunas de las cadenas de error comunes:

Código HTTP Error String Descripción
400 INVALID_ARGUMENT Falta el parámetro user_identifier o loyalty_tier, o bien 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 de 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 enum 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, como 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 proporciona 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 solicita 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: Validación del identificador:

  • La API realiza verificaciones de formato básicas en los identificadores (por ejemplo, la estructura del correo electrónico y la presencia de postalCode en las direcciones).
  • Sin embargo, es posible que algunos identificadores que aprueben las verificaciones iniciales no coincidan con ninguna cuenta de usuario de Google o que no tengan un formato reconocido por el sistema de coincidencia del backend. En esos casos, recibirás la respuesta vacía de éxito silencioso {} 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 cliente para lograr la capacidad de procesamiento necesaria para conjuntos de datos grandes. Debes diseñar tu integración para administrar múltiples 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 ver cómo puedes 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. Por lo 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 de {} como un éxito, entendiendo que significa que los datos no se almacenaron por motivos de privacidad (no hay coincidencia o no hay consentimiento). No vuelvas a intentar ejecutar la solicitud.

  • Verifica el orden de los niveles: Confirma siempre 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 cualquier error 4xx para detectar problemas de integración, en especial los errores 404, que podrían indicar una discrepancia en la comprensión del nivel.

Anterior
Manage loyalty programs