Предоставление учетных записей, контролируемых пользователями – Руководство разработчика API

В этом документе объясняются важные понятия об использовании API обеспечения для создания новых учетных записей Google Analytics.

Введение

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

Прежде чем вы начнете

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

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

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

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

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

Обзор

При создании учетных записей Google Analytics с использованием API обеспечения необходимо учитывать два отдельных процесса:

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

В этом документе для каждого потока описаны шаги и требования высокого уровня.

Технический поток

Общие шаги по использованию Provisioning API для создания новой учетной записи и интеграции с Google Analytics:

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

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

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

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

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

Что вам нужно для выполнения этого шага

Результат этого шага

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

Примечание о токенах и областях:

  • Если вы планируете делать дополнительные запросы на конфигурацию учетной записи пользователя или данные отчетов после создания учетной записи, вы также можете авторизовать дополнительные области на этом этапе. Например, области readonly или edit .
  • Токены доступа имеют ограниченный срок действия. Если вашему приложению требуется доступ к Google Analytics API после окончания срока действия одного токена доступа, вы также можете запросить токен обновления, установив 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 запрос к API учетных записей Google .

Сохраните токен обновления (если применимо).

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

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

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

Что вам нужно для выполнения этого шага

Токен доступа для авторизованного пользователя, как описано в разделе «Аутентификация и авторизация» , а также следующие сведения о предоставлении:

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

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

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

Результат этого шага

После успешного запроса к Provisioning API у вас будет кратковременный билет учетной записи для пользователя. Идентификатор билета учетной записи используется на последнем этапе, чтобы предложить пользователю принять Условия обслуживания (TOS) и активировать свою учетную запись. Пока условия TOS не будут приняты, учетная запись не может быть использована.

Техническая последовательность этого шага

Используя токен доступа для пользователя, полученный во время аутентификации и авторизации, к API обеспечения предоставляется HTTP POST запрос.

Предоставление запроса API для создания билета учетной записи

Ознакомьтесь с методом createAccountTicket в справочнике по API обеспечения, чтобы узнать, как выполнить запрос.

Ответ от API обеспечения

Успешный запрос возвращает ответ 200. Тело ответа содержит билет учетной записи, срок действия которого ограничен. Билет учетной записи состоит из идентификатора и сведений для нового дерева учетной записи.

Подробные сведения об ответе см. в Account Ticket resource в справочнике по API обеспечения.

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

3. Пользователь принимает Условия использования Google Analytics (TOS).

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

Что вам нужно для выполнения этого шага

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

Результат этого шага

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

Техническая последовательность этого шага

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

Сформируйте URL-адрес TOS для посещения пользователем.

Перенаправьте пользователя на страницу TOS и включите идентификатор заявки учетной записи как часть URL-адреса:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Обработка ответа TOS

После того, как пользователь выполнит какое-либо действие на странице TOS, он будет перенаправлен обратно на redirectUri , указанный при создании билета учетной записи . Ответ со страницы TOS будет включен в строку запроса.

Успешные ответы вернут данные о вновь созданной структуре учетной записи, а также исходный accountTicketId :

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

Например, если обработчик TOS для вашего приложения находится по адресу http://www.your-app.com/gaTOS , то его следует установить в качестве redirectUri при создании билетов учетной записи . Обработчик TOS вашего приложения должен ожидать и правильно обрабатывать запросы HTTP GET , которые содержат параметры запроса accountId , webPropertyId , profileId и accountTicketId для случаев, когда билет учетной записи действителен и пользователь принял TOS.

Неудачные ответы будут включать ответ об ошибке:

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

Ваш обработчик TOS также должен правильно обрабатывать запросы HTTP GET , содержащие параметр запроса error , указывающий, что что-то пошло не так. Значение параметра запроса можно использовать для выполнения дальнейших действий или отображения сообщения пользователю:

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

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

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

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

Пользовательский поток

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

Процесс начинается с того, что пользователю предлагаются следующие 2 варианта включения аналитики для его ресурса:

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

При создании новой учетной записи Google Analytics необходимо отправить вместе с запросом на предоставление информацию, такую ​​как имя учетной записи, имя свойства и т. д. В зависимости от имеющейся у вас информации о пользователе и предпочтительного потока, который вы хотите отобразить. Есть 3 основных варианта инициирования пользовательского потока после того, как пользователь нажимает «Создать учетную запись»:

Запросить данные аккаунта после авторизации

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

  1. Пользователь перенаправляется в службу учетных записей Google для потока OAuth 2.0. Если у пользователя нет учетной записи Google или он не вошел в систему, ему будет предложено создать учетную запись Google или войти в систему.
  2. Пользователю предлагается авторизовать приложение для создания учетных записей Google Analytics.
  3. Пользователь принимает запрос разрешений для приложения.
  4. Пользователь перенаправляется к поставщику услуг. Обратите внимание: если пользователь отказывает в авторизации, он все равно перенаправляется обратно к поставщику услуг.
  5. Пользователю предоставляется форма для сбора сведений о создаваемой учетной записи (например, имя учетной записи, имя свойства, имя профиля, часовой пояс, URL-адрес веб-сайта и т. д.).
  6. Пользователь заполняет и отправляет форму, после чего его перенаправляют в Google/показывают Условия использования Google Analytics (TOS).
  7. Пользователь принимает Условия использования.
  8. Пользователь перенаправляется к поставщику услуг, и ему отображается сообщение об успешном создании учетной записи Google Analytics с подробной информацией об учетной записи и способах доступа к ней. Обратите внимание: если пользователь не принимает условия TOS, он все равно перенаправляется обратно к поставщику услуг.

Запросите данные учетной записи перед авторизацией

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

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

Предварительно заполните данные учетной записи или пропустите формы

Если информация об учетной записи пользователя уже доступна (например, URL-адрес веб-сайта, название веб-сайта, часовой пояс и т. д.), то оба приведенных выше варианта можно еще упростить следующим образом:

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