Загрузить доход в Bing Ads с помощью JavaScript

Узнайте, как взаимодействовать с Bing Ads API без SDK

Если вы используете Bing для рекламы своего продукта или привлечения потенциальных клиентов, вы можете использовать платформу Bing Ads для отслеживания конверсий и доходов. Вы можете увеличить доход вручную или с помощью массовой загрузки Excel, но по мере роста вашей компании вы, скорее всего, будете заниматься автоматизацией с помощью API.

Bing Ads API использует запросы и ответы Simple Object Access Protocol (или SOAP), XML-сообщение, которое выглядит следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <NumberToWords xmlns="http://www.dataaccess.com/webservicesserver/">
      <ubiNum>500</ubiNum>
    </NumberToWords>
  </soap:Body>
</soap:Envelope>

Не хорошо.

Чтобы облегчить реализацию API Bing Ads в вашем приложении, Microsoft предоставляет Software Development Kit (или SDK) для нескольких языков (C#, Java, PHP и Python), что означает, что у вас нет написать любой запрос SOAP. К сожалению, SDK для JavaScript недоступен, поэтому нам придется мириться с SOAP-запросами.

Я собираюсь использовать Postman, отличный инструмент для тестирования API без написания единой строки кода, чтобы показать вам, как вы можете использовать Bing Ads API без SDK.

I. Начало работы

Что нужно для начала:

Учетная запись Microsoft Ads (войдите здесь: https://ads.microsoft.com/)
Доступ к порталу Azure
Действительный идентификатор клика Microsoft (уникальный GUID длиной 32 символа, создаваемый при нажатии на объявление).
Базовое понимание почтальона

II. Создайте цель офлайн-конверсии

Чтобы иметь возможность загружать доход, вам сначала нужно создать цель конверсии с уникальным именем. Перейдите на платформу Microsoft Ads, откройте кампанию, для которой вы хотите увеличить доход, и нажмите Инструменты › Конверсии отслеживание › >Цель конверсии.

Нажмите Создать цель конверсии, введите уникальное имя и выберите Офлайн Конверсии. Нажмите Далее и укажите свои предпочтения. Подробнее о возможных вариантах читайте в документации Microsoft здесь.

Обратите внимание, что после создания вам придется подождать 2 часа, прежде чем загружать доход для этой цели конверсии.

III. Аутентификация, получение и доступ к токену

Каждый раз, когда вы отправляете запрос к API, вам необходимо использовать токен доступа с коротким сроком действия (обычно срок действия истекает через 60 минут).

Есть 2 способа получить токен доступа:

Живое подключение
Платформа идентификации Майкрософт

Microsoft рекомендует использовать платформу Microsoft Identity, поэтому я буду использовать этот метод для аутентификации. Если вы застряли на одном из следующих шагов, не стесняйтесь проверить официальную документацию здесь.

1. Зарегистрируйте свое приложение

Сначала зарегистрируйте свое приложение на Портале Azure, нажав Новая регистрация. После того как вы зарегистрировали свое приложение, оно сгенерирует идентификатор приложения, также называемый идентификатором клиента (например, 6731de76–14a6–49ae-97bc-6eba6914391e), который вам понадобится для следующего шаг.

Выберите ссылку Добавить URI перенаправления и убедитесь, что выбран как минимум URI перенаправления: https://login.microsoftonline.com/common/oauth2/nativeclient.

2. Запросить согласие пользователя

Вам необходимо дать согласие на ваше приложение, сгенерировав код авторизации. Скопируйте приведенный ниже URL-адрес и введите свой идентификатор клиента.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fads.manage

Вставьте URL-адрес в свой браузер (обратите внимание, что это не будет работать через Postman). Вам будет предложено перейти на портал входа в Microsoft, где вам нужно будет пройти аутентификацию и дать разрешение для вашего приложения на управление вашими учетными записями Microsoft. После этого вы должны быть перенаправлены на пустую страницу с кодом авторизации в URL-адресе:

https://login.microsoftonline.com/common/oauth2/nativeclient?code=YOUR_AUTHORIZATION_CODE_HERE

Сохраните этот код авторизации для следующего шага. Обратите внимание, что срок его действия истекает через несколько минут.

3. Получите токен обновления

Создайте POST-запрос Postman для https://login.microsoftonline.com/common/oauth2/v2.0/token/.

Выделите тело x-www-form-urlencoded и заполните следующие значения:

client_id: идентификатор вашего клиента.
code: код авторизации, полученный ранее
grant_type:код
redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
область действия:https://ads.microsoft.com/ads.manage offline_access.
арендатор:общий

Нажмите Отправить. Вы должны вернуть токен доступа и токен обновления.

4. Обновите токен доступа

Токен доступа, созданный выше, будет действовать только в течение 60 минут.

Чтобы обновить токен доступа, создайте POST-запрос Postman на https://login.microsoftonline.com/common/oauth2/v2.0/token/.

Выберите тело x-www-form-urlencoded и заполните следующие значения:

client_id: идентификатор вашего клиента.
refresh_token: ваш токен обновления.
grant_type:refresh_token
redirect_uri: https://login.microsoftonline.com/common/oauth2/nativeclient
область действия:https://ads.microsoft.com/ads.manage offline_access.
арендатор:общий

Нажмите Отправить. Вы должны получить новый токен доступа. Поскольку токен обновления действует долго (90 дней), вы сможете повторно использовать этот запрос каждый раз, когда вам понадобится новый токен доступа. Обратите внимание, что ответ также возвращает новый токен обновления.

IV. Применитьофлайн-конверсии

Теперь, когда у вас есть токен доступа, вы, наконец, можете взаимодействовать с Bing Ads API! Мы близки к тому, чтобы сделать нашу первую загрузку дохода!

Создайте новый запрос Postman POST для https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/V13/CampaignManagementService.svc?singleWsdl.

Установите заголовки на:

Тип содержимого: текст/xml; набор символов = utf-8
SOAPAction: Применитьоффлайнконверсии

В body выберите тип raw и XML. Скопируйте запрос Шаблон SOAP, предоставленный в документации Microsoft, вставьте его в тело вашего запроса Postman и заполните недостающие значения:

Заголовки конвертов:

AuthenticationToken:токен доступа из части III.
CustomerAccountId и CustomerId: их можно найти по URL-адресу веб-приложения Microsoft Ads при выборе учетной записи: https://ui.ads.microsoft.com/campaign/vnext/overview?cid=CustomerIdHere&aid=CustomerAccountIdHere
Вы также можете вызвать GetUser и GetAccountInfo, чтобы получить его через запрос API.
Ваш идентификатор разработчика: подробнее здесь

Тело конверта:

Код валюты (например, GBP)
Название конверсии: название, которое вы дали цели конверсии в Части II.
Время конверсии. значение даты и времени (например, 2021–01–27T15:13:13+00:00). Убедитесь, что значение даты и времени позже даты и времени зарегистрированного клика и находится в пределах окна конверсии (максимум 90 дней с момента клика).
ConversionValue: полученный доход.
MicrosoftClickId: убедитесь, что идентификатор клика был сгенерирован из идентификатора учетной записи, заданного в заголовке CustomerAccountId.

Это должно выглядеть так, как показано ниже (конечно, с заполненными идентификаторами вашей учетной записи и токенами):

Нажмите Отправить. Вы должны получить ответ с пустым тегом PartialErrors.
Доход появится в разделе Инструменты›Отслеживание конверсий › Цели конверсии в течение 5 часов.

Подведение итогов

Я надеюсь, что эта статья дала вам представление о том, как использовать API-интерфейсы Bing Ads без SDK. Не стесняйтесь оставлять комментарии, если у вас есть вопросы, и я постараюсь вам помочь. В противном случае вы можете задать вопрос на Форуме разработчиков Microsoft.