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

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

Обзор

Используйте сервис списков электронных адресов для программ лояльности, чтобы загружать данные о программах лояльности. Эти данные используются для органических функций персонализации в Google Поиске, например для показа цен для участников программы. Используйте пользовательский метод ManageLoyaltyCustomerMatch, чтобы связать клиентов с уровнями программы лояльности. Это позволит вам добавлять, обновлять и удалять статусы лояльности на основе идентификаторов пользователей.

Основные понятия

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

Требования

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

  • Создание аккаунта. Убедитесь, что у вас есть активный аккаунт Merchant Center (или авторизованный доступ к аккаунту продавца, если вы сторонний поставщик программы лояльности). Для использования Loyalty Customer Match Service не нужно создавать аккаунт Google Рекламы.
  • Настройка программы лояльности. Включите программу лояльности в аккаунте 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"
  }

Поля loyaltyCustomer

  • userIdentifier – набор идентификаторов, используемых для сопоставления клиента. В userIdentifier должно быть указано хотя бы одно действительное поле.
  • loyaltyTier – уровень программы лояльности, к которому относится клиент. Соответствует порядку уровня в настройках Merchant Center. Подробнее о сопоставлении loyaltyTier… Чтобы удалить существующую связь, используйте значение NON_MEMBER.
  • pointBalance – текущий баланс баллов клиента.

Поля userIdentifier

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

  • emailAddress – адрес электронной почты клиента.
  • address – физический адрес клиента. Укажите почтовый индекс.
  • phoneNumber – номер телефона клиента. Рекомендуется использовать формат E.164.

Как работает сопоставление loyaltyTier

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

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

Пример

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

  1. Название уровня: "Silver Status", метка уровня: "silver"
  2. Название уровня: "Золотой уровень", метка уровня: "gold"
  3. Название уровня: "Platinum Elite", метка уровня: "platinum"

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

  • Чтобы присвоить клиенту серебряный статус, используйте loyaltyTier: TIER1.
  • Чтобы присвоить клиенту статус "Золотой", необходимо использовать loyaltyTier: TIER2.
  • Чтобы присвоить клиенту статус Platinum Elite, необходимо использовать 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 соответствует первому определенному уровню (например, 'Basic'), а TIER2 – второму (например, 'Premium').

Чтобы добавить клиента на уровень 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 INVALID_ARGUMENT Отсутствует user_identifier или loyalty_tier, или идентификатор пуст.
401 UNAUTHENTICATED Учетные данные недействительны или отсутствуют.
403 PERMISSION_DENIED У аутентифицированного пользователя нет доступа к указанному аккаунту Merchant Center.
404 NOT_FOUND Указанная метка уровня программы лояльности не существует в вашей конфигурации.
412 FAILED_PRECONDITION В вашем аккаунте не настроена программа лояльности.
429 RESOURCE_EXHAUSTED Квота исчерпана.

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

Пример для 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 – недопустимое значение enum для 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, поэтому он не считается действительным идентификатором.

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

Сценарий. Продавец настроил только один уровень в Merchant Center.

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

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

Если запрос содержит неправильно сформированный параметр 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 запросов в минуту. Подробнее о том, как отслеживать и проверять квоты…

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

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

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

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

Назад
Manage loyalty programs