В этой статье описываются основные принципы использования Provisioning API для создания аккаунтов Google Analytics.
Введение
Provisioning API позволяет создавать новые аккаунты и внедрять Google Analytics для ваших клиентов. Он ориентирован, прежде всего, на соответствующих поставщиков услуг и крупных партнеров. Если вы ещё не знакомы с Provisioning API, прочитайте эту статью.
Подготовка к работе
Доступ ко всем Google Analytics API осуществляется одинаково. Прежде чем начать работу с API синхронизации, ознакомьтесь со следующими материалами:
- Списком клиентских библиотек для всех языков программирования, которые поддерживает этот API.
- Справочным руководством по интерфейсу API и доступу к данным без использования клиентских библиотек.
В каждой библиотеке реализован один служебный объект Google Analytics, который обеспечивает доступ ко всем данным API синхронизации. Чтобы создать служебный объект, обычно нужно выполнить следующие действия:
- Зарегистрировать приложение в Google API Console.
- Разрешить создавать новые аккаунты Google Analytics.
- Создать служебный объект Google Analytics.
Если вы не выполнили эти действия, перед продолжением прочитайте вводное руководство по Google Analytics API, в котором описывается, с чего нужно начинать создание приложения. Это информация поможет вам в использовании Google Analytics API для работы с реальными приложениями.
Обзор
Создание аккаунтов Google Analytics с помощью Provisioning API следует рассматривать с двух точек зрения:
- Техническая реализация – программная подготовка аккаунта Google Analytics для пользователя.
- Действия пользователя – процедуры создания аккаунта, выполняемые пользователем.
В этой статье будут рассмотрены общие процессы и требования для обоих аспектов реализации.
Техническая реализация
Для создания нового аккаунта и интеграции с Google Analytics с использованием Provisioning API нужно выполнить следующие действия:
- Запросить у пользователя полномочия и разрешения для приложения или службы по протоколу OAuth 2.0.
- Создать билет аккаунта с помощью Provisioning API.
- Перенаправить пользователя на страницу, где нужно принять условия использования, и обработать ответ.
- Настроить аккаунт и возможности интеграции (необязательно).
Таким образом, вы создадите аккаунт Google Analytics для пользователя и получите идентификаторы самого аккаунта, ресурса и представления (профиля) для дальнейшей работы.
Для каждого шага в этой статье описываются требования, результаты и подробности технической реализации.
1. Аутентификация и авторизация
Пользователь должен предоставить вашему приложению разрешения на создание аккаунта Google Analytics от его имени. Для этой цели применяется процесс OAuth 2.0 на стороне веб-сервера.
Что вам понадобится
- Идентификатор клиента (
Client ID
) используемого проекта, который можно получить в Google Developers Console. Подробнее о процессе OAuth 2.0 на стороне веб-сервера... - URI переадресации, по которому перейдет пользователь и будет отправлен ответ OAuth 2.0.
- Настроить
Redirect URI
и получитьClient ID
для проекта можно с помощью Google Developers Console. - Значение этого параметра должно полностью совпадать с одним из зарегистрированных в Google Developers Console, включая префиксы http и https, а также конечные символы косой черты (/).
- Настроить
- Область доступа к Google Analytics Provisioning API с разрешениями на авторизацию.
Результаты
По завершении процесса авторизации 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://analytics.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 для своего ресурса:
- Создать новый аккаунт Google Analytics.
- Или использовать существующий (здесь этот вариант не рассматривается). Подробнее о доступе к данным конфигурации Google Analytics...
При создании нового аккаунта Google Analytics в запрос включается ряд обязательных параметров, включая названия аккаунта, ресурса и т. д. После того, как пользователь нажмет кнопку "Создать аккаунт", как правило, выполняется одна из трех основных процедур:
Как запросить сведения об аккаунте после авторизации
В этом случае пользователь вводит сведения об аккаунте в середине процесса. Вот как это выглядит:
- Пользователь перенаправляется в сервис "Google Аккаунты" для авторизации по протоколу OAuth 2.0. Здесь пользователь должен создать новый аккаунт Google или войти в существующий.
- Появляется запрос разрешений на создание аккаунтов Google Analytics.
- Пользователь предоставляет приложению нужные разрешения.
- Пользователь возвращается на страницу поставщика услуг, даже если он не предоставил запрошенные разрешения.
- Появляется форма для ввода сведений о создаваемом аккаунте, включая названия аккаунта, ресурса и профиля, часовой пояс, URL веб-сайта и т. д.
- Пользователь заполняет и отправляет форму, после чего автоматически переходит на страницу с условиями использования Google Analytics.
- Пользователь принимает условия использования.
- Пользователь снова возвращается на страницу поставщика услуг, где показывается информация об успешном создании аккаунта Google Analytics и порядке доступа к нему. Страница поставщика услуг откроется, даже если пользователь не принимает условия.
Как запросить сведения об аккаунте до авторизации
В этом случае сведения о конфигурации аккаунта запрашиваются до его создания. Вот как это выглядит:
- На сайте поставщика услуг показывается форма для ввода сведений о создаваемом аккаунте, включая названия аккаунта, ресурса и профиля, часовой пояс, URL веб-сайта и т. д.
- Пользователь заполняет и отправляет форму, после чего перенаправляется в сервис "Google Аккаунты" для авторизации по протоколу OAuth 2.0. Здесь пользователь должен создать новый аккаунт Google или войти в существующий.
- Появляется запрос разрешений на создание аккаунтов Google Analytics.
- Пользователь предоставляет приложению нужные разрешения.
- Пользователь возвращается на страницу поставщика услуг.
- Пользователь автоматически переходит на страницу с условиями использования Google Analytics.
- Пользователь принимает условия использования.
- Пользователь снова возвращается на страницу поставщика услуг, где показывается информация об успешном создании аккаунта Google Analytics и порядке доступа к нему.
Как заранее ввести сведения об аккаунте или пропустить формы
Если сведения об аккаунте пользователя, такие как URL и название веб-сайта или часовой пояс, известны заранее, предыдущие процедуры будут ещё проще. Что для этого нужно:
- Предоставить пользователю заполненную форму, поля которой можно изменять.
- Пропустить этап, на котором заполняется форма, и автоматически создать аккаунт на основе имеющихся сведений.