Provisioning API: руководство для разработчиков

В этой статье описываются основные принципы использования Provisioning API для создания аккаунтов Google Analytics.

Введение

Provisioning API позволяет создавать новые аккаунты и внедрять Google Analytics для ваших клиентов. Он ориентирован, прежде всего, на соответствующих поставщиков услуг и крупных партнеров. Если вы ещё не знакомы с Provisioning API, прочитайте эту статью.

Подготовка к работе

Доступ ко всем Google Analytics API осуществляется одинаково. Прежде чем начать работу с Provisioning API, ознакомьтесь со следующими материалами:

  • Клиентские библиотеки. На этой странице представлены клиентские библиотеки для всех языков программирования, которые поддерживает этот API.
  • Справочное руководство по интерфейсу API и доступу к данным без использования клиентских библиотек.

В каждой библиотеке реализован один объект службы Google Analytics, который обеспечивает доступ ко всем данным Provisioning API. Чтобы создать объект службы, обычно нужно выполнить следующие действия:

  1. Зарегистрируйте приложение в Google API Console.
  2. Разрешите создавать новые аккаунты Google Analytics.
  3. Создайте объект службы Google Analytics.

Если вы не выполнили эти действия, перед продолжением прочитайте вводное руководство по Google Analytics API, в котором описывается, с чего нужно начинать создание приложения на его основе. Это поможет вам использовать Google Analytics API для работы с реальными приложениями.

Обзор

Создание аккаунтов Google Analytics с помощью Provisioning API следует рассматривать с двух точек зрения:

В этой статье будут рассмотрены общие процессы и требования для обоих аспектов реализации.

Техническая реализация

Для создания нового аккаунта и интеграции с Google Analytics с использованием Provisioning API нужно выполнить следующие действия:

  1. Запросить у пользователя полномочия и разрешения для приложения или службы по протоколу OAuth 2.0.
  2. Создать билет аккаунта с помощью Provisioning API.
  3. Перенаправить пользователя на страницу, где нужно принять условия использования, и обработать ответ.
  4. Настроить аккаунт и возможности интеграции (необязательно).

Таким образом, вы создадите аккаунт Google Analytics для пользователя и получите идентификаторы самого аккаунта, ресурса и представления (профиля) для дальнейшей работы.

Для каждого шага в этой статье описываются требования, результаты и подробности технической реализации.

1. Аутентификация и авторизация

Пользователь должен предоставить вашему приложению разрешения на создание аккаунта Google Analytics от его имени. Для этой цели применяется процесс OAuth 2.0 на стороне веб-сервера.

Что вам понадобится

Результаты

После результатам процесса OAuth 2.0 ваше приложение получит от пользователя разрешения на подготовку аккаунта от его имени, а также соответствующий токен доступа.

При работе с токенами и областями доступа учитывайте следующее:

  • Если после создания аккаунта вы планируете запрашивать данные конфигурации или отчетов, могут потребоваться дополнительные области доступа, например readonly или edit.
  • Срок действия токенов доступа ограничен, и по его окончании вам могут потребоваться токены обновления (access_type=offline). Они нужны для получения новых токенов доступа и должны храниться в надежном месте отдельно для каждого пользователя. Подробнее об офлайн-режиме...

Техническая реализация

Сначала нужно получить токен доступа для пользователя. Для этого следует выполнить процесс OAuth 2.0 на стороне веб-сервера, направить пользователя на страницу сервиса "Google Аккаунты", а после его авторизации и возвращения в ваш сервис обработать полученный ответ.

Как сформировать URL OAuth 2.0 для перехода пользователя

При нажатии кнопки "Начать работу" или "Создать аккаунт" пользователя нужно направить по ссылке в процесс OAuth 2.0, где он предоставит необходимые разрешения. Пример:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Как обработать ответ сервиса "Google Аккаунты"

Чтобы предоставит вашему приложению доступ, пользователь переходит по redirect_uri с URL, содержащим код авторизации в параметре запроса. Если пользователь подтверждает запрос, код авторизации для токена доступа передается в запросе POST в Google Accounts API.

Как сохранить токен обновления (если необходимо)

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

2. Создание билета аккаунта с помощью Provisioning API

Полученный токен доступа нужно включить в запрос к Provisioning API для создания билета аккаунта, без которого нельзя создать аккаунт для пользователя.

Что вам понадобится

Токен доступа, полученный на предыдущем шаге, а также следующая информация:

  • URI переадресации
    • Указывает, куда перейдет пользователь со страницы с условиями использования Google Analytics, и может отличаться от URI, заданного в процессе авторизации OAuth 2.0.
    • Значение этого параметра должно полностью совпадать с одним из зарегистрированных в Google Developers Console, включая префиксы http и https, а также конечные символы косой черты (/).
  • Поля аккаунта
    • Свойство аккаунта name является обязательным.
  • Поля веб-ресурса
    • Свойство ресурса name является обязательным.
    • Свойство websiteUrl является обязательным.
  • Поля профиля
    • Свойство профиля name является обязательным.
    • При необходимости задайте свойство timezone (часовой пояс), которое по умолчанию имеет значение America/Los_Angeles.

При создании билета можно задавать только показанные выше базовые поля. Остальные настройки ресурса или представления (профиля) выполняются после создания аккаунта с помощью Management API.

Подробнее о полях аккаунтов, ресурсов и представлений (профилей) читайте в справке по API.

Результаты

В ответ на запрос Provisioning API возвращает краткосрочный билет аккаунта для пользователя. Его идентификатор нужно указать, когда пользователь принимает условия использования и активирует свой аккаунт. До тех пор, пока эти действия не выполнены, аккаунт будет недоступен.

Техническая реализация

Токен доступа, полученный ранее, включается в запрос HTTP POST к Provisioning API.

Как создать билет аккаунта по запросу к Provisioning API

Более подробно читайте в описании метода createAccountTicket в справке по Provisioning API.

Как обработать ответ Provisioning API

В случае успеха возвращается ответ с кодом статуса 200, в теле которого представлен краткосрочный билет аккаунта, содержащий идентификатор и сведения о структуре нового аккаунта.

Подробнее о ресурсе типа "Билет аккаунта" читайте в справке по Provisioning API.

Также не забудьте реализовать обработку ошибок.

3. Принятие условий использования Google Analytics

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

Что вам понадобится

Идентификатор билета аккаунта для авторизованного пользователя.

Результаты

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

Техническая реализация

Указав идентификатор билета, перенаправьте пользователя на страницу, где он сможет принять условия использования Google Analytics, а затем обработайте полученный от API ответ.

Как создать URL страницы с условиями использования

Включите в URL идентификатор билета аккаунта:

https://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?api.accountTicketId={account_ticket_id}
Как обработать полученный ответ

Закончив работу на странице с условиями использования, пользователь возвращается по redirectUri, который был указан при создании билета аккаунта. В строку запроса при этом включается ответ, полученный на странице.

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

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Пример URL страницы с условиями использования: http://www.your-app.com/gaTOS. Укажите его в параметре redirectUri при создании билета аккаунта. Если есть действительный билет аккаунта, и пользователь принял условия использования, обработчик этой страницы должен принимать запросы HTTP GET с параметрами accountId, webPropertyId, profileId и accountTicketId.

В случае неудачи в ответ включаются сведения об ошибке:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

В таком случае обработчик должен принимать запросы HTTP GET с параметром error query parameter, indicating something went wrong. значение которого позволяет определить пути решения проблемы и показать пользователю сообщение об ошибке:

  • error=user_cancel – пользователь не принял условия использования;
  • error=max_accounts_reached – пользователь уже создал максимально возможное количество аккаунтов Google Analytics;
  • error=backend_error – общая ошибка сервера, не относящаяся к предыдущим категориям.

4. Возможности интеграции (дополнительно)

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

  • Вы можете автоматически добавлять стандартный фрагмент кода отслеживания Google Analytics с идентификатором ресурса из созданного аккаунта на любые страницы веб-сайта пользователя.
  • Вы можете автоматически настраивать ресурс пользователя с помощью Management API.
  • Пользователь сможет получать отчеты из вашего продукта (панель администрирования) с помощью Embed API или Core Reporting API.

Действия пользователя

В этом разделе показана процедура создания аккаунта с точки зрения пользовате.

Сначала пользователь должен выбрать, как включить Google Analytics для своего ресурса:

  1. Создать новый аккаунт Google Analytics.
  2. Или использовать существующий (здесь этот вариант не рассматривается). Подробнее о доступе к данным конфигурации Google Analytics...

При создании нового аккаунта Google Analytics в запрос включается ряд обязательных параметров, включая названия аккаунта, ресурса и т. д. После того, как пользователь нажмет кнопку "Создать аккаунт", как правило, выполняется одна из трех основных процедур:

Как запросить сведения об аккаунте после авторизации

В этом случае пользователь вводит сведения об аккаунте в середине процесса. Вот как это выглядит:

  1. Пользователь перенаправляется в сервис "Google Аккаунты" для авторизации по протоколу OAuth 2.0. Здесь пользователь должен создать новый аккаунт Google или войти в существующий.
  2. Появляется запрос разрешений на создание аккаунтов Google Analytics.
  3. Пользователь предоставляет приложению нужные разрешения.
  4. Пользователь возвращается на страницу поставщика услуг, даже если он не предоставил запрошенные разрешения.
  5. Появляется форма для ввода сведений о создаваемом аккаунте, включая названия аккаунта, ресурса и профиля, часовой пояс, URL веб-сайта и т. д.
  6. Пользователь заполняет и отправляет форму, после чего автоматически переходит на страницу с условиями использования Google Analytics.
  7. Пользователь принимает условия использования.
  8. Пользователь снова возвращается на страницу поставщика услуг, где показывается информация об успешном создании аккаунта Google Analytics и порядке доступа к нему. Страница поставщика услуг откроется, даже если пользователь не принимает условия.

Как запросить сведения об аккаунте до авторизации

В этом случае сведения о конфигурации аккаунта запрашиваются до его создания. Вот как это выглядит:

  1. На сайте поставщика услуг показывается форма для ввода сведений о создаваемом аккаунте, включая названия аккаунта, ресурса и профиля, часовой пояс, URL веб-сайта и т. д.
  2. Пользователь заполняет и отправляет форму, после чего перенаправляется в сервис "Google Аккаунты" для авторизации по протоколу OAuth 2.0. Здесь пользователь должен создать новый аккаунт Google или войти в существующий.
  3. Появляется запрос разрешений на создание аккаунтов Google Analytics.
  4. Пользователь предоставляет приложению нужные разрешения.
  5. Пользователь возвращается на страницу поставщика услуг.
  6. Пользователь автоматически переходит на страницу с условиями использования Google Analytics.
  7. Пользователь принимает условия использования.
  8. Пользователь снова возвращается на страницу поставщика услуг, где показывается информация об успешном создании аккаунта Google Analytics и порядке доступа к нему.

Как заранее ввести сведения об аккаунте или пропустить формы

Если сведения об аккаунте пользователя, такие как URL и название веб-сайта или часовой пояс, известны заранее, предыдущие процедуры будут ещё проще. Что для этого нужно:

  • Предоставить пользователю заполненную форму, поля которой можно изменять.
  • Пропустить этап, на котором заполняется форма, и автоматически создать аккаунт на основе имеющихся сведений.