Обзор сервиса сопоставления данных о клиентах программы лояльности

В этом руководстве описывается, как использовать сервис сопоставления данных о лояльных клиентах в API для продавцов. Этот сервис позволяет продавцам управлять данными о лояльности клиентов, такими как идентификаторы пользователей и информация о уровнях, для органической персонализации в поиске Google, без необходимости активного аккаунта Google Ads.

Обзор

Используйте сервис сопоставления данных о лояльных клиентах (Loyalty Customer Match Service) для загрузки данных о программе лояльности, которые затем используются для предоставления персонализированных функций лояльности в поиске Google, например, для отображения цен, специфичных для участников программы. Вы используете пользовательский метод ManageLoyaltyCustomerMatch для связывания ваших клиентов с уровнями программы лояльности, что позволяет добавлять , обновлять или удалять их статус лояльности на основе идентификаторов пользователей.

Ключевые понятия

  • Единый интерфейс: уникальная точка доступа для добавления, обновления или удаления информации об уровнях лояльности клиентов.
  • Принцип приоритета конфиденциальности: для защиты конфиденциальности пользователей и предотвращения несанкционированного доступа к учетным записям API не поддерживает операции GET или LIST , что гарантирует управление данными без их повторного получения или аудита.
  • Гибкая идентификация: сопоставление пользователей с использованием как минимум одного допустимого идентификатора, такого как адрес электронной почты, физический адрес или номер телефона.
  • Обработка данных на основе согласия: Сервис хранит и использует данные клиентов только тогда, когда конечный пользователь предоставил Google необходимое согласие . Для защиты и предотвращения проверки существования учетной записи или статуса согласия сервис возвращает сообщение об успешном завершении, если совпадение не найдено или согласие не предоставлено.

Предварительные требования

Для использования сервиса сопоставления лояльных клиентов выполните следующие требования:

  • Настройка аккаунта: Убедитесь, что у вас есть активный аккаунт в Merchant Center. Для использования сервиса сопоставления лояльных клиентов создавать аккаунт Google Ads не требуется.
  • Настройка программы лояльности: включите программу лояльности в своем аккаунте Merchant Center и убедитесь, что вы определили уровни лояльности.
  • Учитывайте порядок уровней: обратите внимание на порядок определения уровней лояльности в пользовательском интерфейсе Merchant Center. API использует именно эту последовательность для сопоставления перечислений.

Метод: ManageLoyaltyCustomerMatch

Метод ManageLoyaltyCustomerMatch служит центральным интерфейсом для управления связями лояльности клиентов. На основе предоставленных входных данных сервис автоматически определяет, следует ли добавить, обновить или удалить статус уровня лояльности клиента. Операция идемпотентна : повторные идентичные запросы имеют тот же эффект, что и один запрос.

Следующий запрос демонстрирует, как управлять программами лояльности клиентов через API:

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

Данный запрос определяет следующие обязательные параметры пути:

  • api_version : Версия API, например, v1.
  • account_id : Идентификатор учетной записи в Merchant Center.

Включите объект loyaltyCustomer в тело запроса.

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

лояльностьПоля клиента

  • userIdentifier : Набор идентификаторов, используемых для сопоставления клиента. Необходимо указать и подтвердить хотя бы одно допустимое поле в userIdentifier.
  • loyaltyTier : Уровень лояльности, который необходимо связать с клиентом. Соответствует порядку уровней в настройках Merchant Center. Подробнее см. раздел «Понимание сопоставления loyaltyTier . Используйте NON_MEMBER для удаления существующей связи.
  • pointBalance : Текущий баланс баллов клиента.

поля идентификатора пользователя

Укажите хотя бы одно из следующих полей:

  • emailAddress : Адрес электронной почты клиента.
  • Адрес : Физический адрес клиента. Почтовый индекс обязателен.
  • phoneNumber : Номер телефона клиента. Рекомендуется использовать формат E.164.

Разберитесь в системе сопоставления loyaltyTier .

API не использует пользовательские имена. Значения перечисления loyaltyTier ( TIER1 до TIER7 ) являются семантическими метками. Они не используют пользовательские имена (например, "Gold Rewards") или пользовательские метки (например, "gold_tier"), которые вы назначили в пользовательском интерфейсе Merchant Center. Вместо этого они строго соответствуют порядку, в котором вы определили уровни в настройках программы лояльности в Merchant Center:

  • TIER1 : Соответствует первому уровню, указанному в настройках программы лояльности вашего Merchant Center.
  • TIER2 : Соответствует второму уровню, указанному в настройках программы лояльности вашего Merchant Center.
  • TIER3 TIER7 : соответствуют третьему, второму, третьему, третьему, третьему, четвертому и седьмому уровням, указанным в настройках программы лояльности вашего Merchant Center.

Пример:

Если в вашей программе лояльности Merchant Center уровни определены в следующем порядке:

  1. Название уровня: "Серебряный статус" , Метка уровня: "серебро"
  2. Название уровня: "Золотой участник" , Метка уровня: "золотой"
  3. Название уровня: "Платиновая элита" , Метка уровня: "платина"

Затем в вызовах API accounts.loyaltyCustomers.manage :

  • Для присвоения клиенту «Серебряного статуса» необходимо использовать loyaltyTier: TIER1 .
  • Для присвоения клиенту статуса «Золотой участник» необходимо использовать loyaltyTier: TIER2 .
  • Для присвоения клиенту статуса «Платиновый элитный» необходимо использовать loyaltyTier: TIER3 .

Значения перечисления LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (Используется для обозначения прекращения участия клиента в программе лояльности)

Разберитесь в содержимом ответа ManageLoyaltyCustomerMatch.

Метод ManageLoyaltyCustomerMatch возвращает объект ManageLoyaltyCustomerMatchResponse :

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

Важные соображения при подготовке ответов

  • Успешное обновление/вставка (данные сохранены): Для успешного сохранения или обновления информации о принадлежности клиента к уровню лояльности необходимо выполнить следующие условия:

    • Вы сопоставляете пользователя Google с предоставленным userIdentifier .
    • Вы задали параметр loyaltyTier в запросе на допустимое значение, отличное от NON_MEMBER
    • Соответствующий пользователь дал согласие на использование данных программы лояльности.

В ответе содержится объект loyaltyCustomer из вашего запроса, указывающий на то, что сервис успешно обработал и сохранил данные:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Успешное удаление: Для успешного удаления существующих программ лояльности клиента у данного продавца должны быть выполнены следующие условия:
    • Вы сопоставляете пользователя Google с предоставленным userIdentifier .
    • В запросе параметр loyaltyTier установлен на NON_MEMBER

В ответ приходит пустой JSON-объект:

{}
  • Нет совпадения / нет согласия (тихий успех): Если предоставленный userIdentifier не соответствует учетной записи Google или если найденный пользователь не дал согласия на использование данных программы лояльности, API возвращает статус HTTP 200 OK с пустым JSON-объектом: {} . Это происходит как при попытке обновления, так и при попытке удаления.

Примеры

TIER1 соответствует первому определенному уровню (например, «Базовый» ), а TIER2 — второму уровню (например, «Премиум» ).

Чтобы добавить клиента в категорию TIER2 или обновить его статус, используя адрес электронной почты, отправьте следующий запрос:

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

Когда пользователь успешно сопоставлен с данными и дал согласие, API возвращает следующий ответ:

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

Если совпадение не найдено или пользователь не дал согласия, API возвращает следующий ответ:

{}

Чтобы отменить участие клиента в программе лояльности, используя номер телефона, отправьте следующий запрос:

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

Независимо от того, существовала ли запись, API возвращает следующий успешный ответ: 

{}

Для добавления или обновления данных клиента с использованием нескольких идентификаторов отправьте следующий запрос: 

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

Ответная реакция аналогична первому примеру, в зависимости от совпадения и согласия.

Обработка ошибок

API использует стандартные HTTP-коды. Типичные строки ошибок включают:

HTTP-код Строка ошибки Описание
400 НЕВЕРНЫЙ АРГУМЕНТ Отсутствует user_identifier или loyalty_tier , либо идентификатор пуст.
401 НЕПОДТВЕРЖДЕННЫЙ Неверные или отсутствующие учетные данные.
403 ДОСТУП ЗАПРЕЩЕН У авторизованного пользователя нет доступа к указанному аккаунту в Merchant Center.
404 НЕ НАЙДЕНО Указанный уровень лояльности отсутствует в вашей конфигурации.
412 НЕУДАЧНОЕ ПРЕДУСЛОВИЕ В вашем аккаунте не настроена программа лояльности.
429 ИСТЕЧЕНИЕ РЕСУРСОВ Достигнут лимит квоты.

Примеры ошибок

Пример ошибки 404 NOT_FOUND:

Любой действительный запрос к идентификатору учетной записи, для которой не настроена программа лояльности.

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: У торгового счета в указанном пути отсутствует активная программа лояльности.

Примеры ошибок 400 INVALID_ARGUMENT:

Ошибка возникает, если запрос содержит недопустимое значение для поля loyaltyTier : 

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

API возвращает следующий ответ с ошибкой: 

{
  "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\""
          }
        ]
      }
    ]
  }
}

Причина: TIER11 не является допустимым значением перечисления для loyaltyTier . Та же ошибка может возникнуть при попытке указать TIER2 , когда доступен только один уровень.

Ошибка возникает, если в теле запроса отсутствует обязательное поле loyaltyTier : 

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

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: Поле loyaltyTier является обязательным для заполнения.

Ошибка возникает, если идентификатор адреса неполный, например, если отсутствует поле postalCode: 

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

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: Указан адрес, но отсутствует обязательное поле postalCode , поэтому он не считается допустимым идентификатором.

Ошибка возникает, если вы запрашиваете индекс уровня, выходящий за пределы допустимых значений для настроенной программы:

Ситуация: В Центре для продавцов у продавца настроен только один уровень обслуживания. 

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

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: запрашивается второй уровень , но в программе лояльности, привязанной к учетной записи, второй уровень не определен.

Ошибка возникает, если запрос содержит некорректный emailAddress : 

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

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: Неверный формат адреса электронной почты.

Ошибка возникает, если объект userIdentifier пуст: 

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

API возвращает следующий ответ с ошибкой: 

{
  "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"
        }
      }
    ]
  }
}

Причина: Объект userIdentifier присутствует, но не содержит фактических полей идентификатора.

Примечание: Проверка идентификатора.

  • API выполняет базовые проверки формата идентификаторов (например, структуры электронной почты, наличия postalCode в адресах).
  • Однако некоторые идентификаторы, прошедшие первоначальную проверку, могут не соответствовать ни одной учетной записи пользователя Google или могут быть не в формате, распознаваемом системой сопоставления на стороне сервера. В таких случаях вы получите пустой ответ {} с HTTP-статусом 200 OK .

Передовые методы

Следуйте этим рекомендациям, чтобы оптимизировать интеграцию.

  • Для крупномасштабной интеграции: поскольку API работает на основе каждого запроса, для обеспечения необходимой пропускной способности для больших наборов данных требуется параллельная обработка на стороне клиента. Ваша интеграция должна быть спроектирована таким образом, чтобы обрабатывать несколько одновременных запросов. Рекомендации по структурированию вашей реализации для обработки больших объемов данных с помощью параллелизации см. в нашем руководстве по отправке нескольких запросов .

  • Управление квотами: Квота по умолчанию составляет 1 000 000 запросов в день и 10 000 запросов в минуту . Чтобы узнать, как отслеживать и проверять свои квоты, см. раздел «Квоты и лимиты» .

  • Приоритет отдается адресу электронной почты: по возможности включайте emailAddress клиента в userIdentifier . Адреса электронной почты, как правило, являются наиболее точным и надежным идентификатором для сопоставления пользователей с их учетными записями Google.

  • Обработка пустых ответов: Разработайте приложение таким образом, чтобы оно корректно интерпретировало пустые ответы в виде фигурных скобок {} как успешный результат, понимая, что данные не были сохранены по соображениям конфиденциальности (нет совпадения или нет согласия). Не повторяйте запрос.

  • Проверка порядка уровней: Всегда проверяйте порядок уровней лояльности в пользовательском интерфейсе Merchant Center, чтобы убедиться, что вы используете правильные значения перечисления TIER1 – TIER7 в своих вызовах API. Это сопоставление основано на порядке, определенном в пользовательском интерфейсе, а не на их названиях.

  • Отслеживание ошибок: регистрируйте и отслеживайте ответы API, обращая внимание на ошибки 4xx , чтобы выявлять проблемы интеграции, особенно ошибки 404 , которые могут указывать на несоответствие в понимании уровней.