Provisioning API - Developer Guide

This document explains important concepts about using the Provisioning API to create new Google Analytics accounts.

Introduction

The Provisioning API can be used to create new Google Analytics accounts and enable Google Analytics for your customers at scale. It is intended for qualified service providers and large partners. Visit the Provisioning API Overview for an introduction to the Provisioning API.

Before You Begin

All Google Analytics APIs are accessed in a similar manner. Before you begin with the Provisioning API you should:

  • Read the client libraries page for a complete list of programming language specific client libraries that work with the API.
  • Read the Reference Guide to learn about the API interface and accessing data without a client library.

Each client library provides a single analytics service object to access the Provisioning API. To create the service object you generally have to go through the following steps:

  1. Register your application in the Google API Console.
  2. Authorize to create a new Google Analytics account.
  3. Create an Analytics service object.

If you haven't completed these steps, please stop and read the Hello Google Analytics API Tutorial. This tutorial will walk you through the initial steps of building a Google Analytics API application. Once complete, you will understand how to access Google Analytics APIs to perform real-world tasks.

Overview

When creating Google Analytics accounts using the Provisioning API, there are 2 separate flows to consider:

  • Technical Flow: The end-to-end flow to programmatically provision a Google Analytics account for a user.
  • User Flow: The implementation considerations you should make for the account creation flow from the user's perspective.

This document describes for each flow the high-level steps and requirements.

Technical Flow

The high-level steps to use the Provisioning API to create a new account and integrate with Google Analytics are:

  1. Prompt user to authenticate and authorize the application/service using OAuth 2.0.
  2. Create an Account Ticket using the Provisioning API.
  3. Redirect the user to accept the Google Analytics Terms of Service (TOS) and handle the response.
  4. (Optional) Configure account and integration opportunities.

If all of these steps are completed successfully a Google Analytics account will be created for the user and you will have the Account ID, Property ID, and View (Profile) ID for the new account.

For each step below there are Requirements to complete the step, Outcomes of the step, and a description of the Technical Flow for the step.

1. Authentication and Authorization

Each user needs to authorize your application and grant it the capability to provision a Google Analytics account on their behalf. The OAuth 2.0 Web Server application flow is suggested to carry out this step.

What you need to complete this step

The outcome of this step

Once the OAuth 2.0 flow is completed, the user will have authorized your application to provision an account on his/her behalf and you will have an Access Token for the user.

Note on Tokens and Scopes:

  • If you intend to make additional requests for the user’s account configuration or reporting data after the account is created then you could also authorize additional scopes during this step. For example, the readonly or edit scopes.
  • Access tokens have limited lifetimes. If your application needs access to the Google Analytics API beyond the lifetime of a single access token then you can also request a refresh token by setting the access_type=offline. A Refresh Token should be saved in secure long-term storage for each user since it allows your application to obtain new access tokens. See Offline access for additional details.

The technical flow for this step

You need to get an Access Token for the user. Based on the flow described at OAuth 2.0 Web Server, send the user to the Google Accounts service, and then handle the response when the user is redirected back to your service after completing the auth flow.

Form the OAuth 2.0 URL for the user to visit

When the user clicks on a button or link to Get Started or Create an Account the link should point to the start of the OAuth 2.0 flow to ask the user to grant provisioning permissions. For example:

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}
Handle the Response from Google Accounts Service

Once the user makes their decision to grant your application access, they will be redirected to the redirect_uri as specified in the URL you formed with a query parameter containing an authorization code. If the user approved the request then the authorization code response can be used to exchange the authorization code for an access token by making a POST request to the Google Accounts API.

Save the Refresh Token (if applicable)

The access token will be used in the next step so you can temporarily store it. If you also requested a refresh token for the user then you should store this securely for longer-term usage. A refresh token is long-lived and can be used to issue new access tokens.

2. Create an Account Ticket using the Provisioning API

Once you have an access token for the authorized user, you can use this to make a request to the Provisioning API to create an Account Ticket for the user. The Account Ticket is the first step to creating an account for a user.

What you need to complete this step

An access token for the authorized user as described in Authentication and Authorization and the following provisioning details:

  • Redirect URI
    • Defines where the user is redirected to after the Google Analytics Terms of Service (TOS) page. It can be different from the redirect URI specified during the OAuth 2.0 authorization flow.
    • The value of the Redirect URI parameter must exactly match one of the values registered in the Google Developers Console (including the http or https schemes, case, and trailing '/').
  • Account fields
    • A name property is required for the account.
  • Web Property fields
    • A name property is required for the property.
    • A websiteUrl is required.
  • Profile fields
    • A name property is required for the profile.
    • A timezone can optionally be provided. Default is America/Los_Angeles.

When creating an account ticket, only the basic fields identified above can be set. Once the account has been created, any additional configuration changes to the property or view (profile) can be made using the Management API.

See the API Reference for Accounts, Properties, and Views (Profiles) for additional details on these fields.

The outcome of this step

After a successful request is made to the Provisioning API, you will have a short-lived Account Ticket for the user. The Account Ticket Id is used in the final step to prompt the user to accept the Terms of Service (TOS) and activate their account. Until the TOS has been accepted the account cannot be used.

The technical flow for this step

Using the access token for the user that was obtained during Authentication and Authorization an HTTP POST request is made to the Provisioning API.

Provisioning API Request to create the Account Ticket

Review the createAccountTicket method in the Provisioning API reference for details on how to make the request.

Response from the Provisioning API

A successful request returns a 200 response. The response body contains an Account Ticket, which is short-lived. The account ticket consists of an ID and details for the new account tree.

Review the Account Ticket resource in the Provisioning API reference for details on the response.

Error responses also need to be handled by the application.

3. User Accepts the Google Analytics Terms of Service (TOS)

After you have an Account Ticket Id for the user, then you can use this with the TOS request to prompt the user to accept the Google Analytics Terms of Service.

What you need to complete this step

An Account Ticket Id for the authorized user.

The outcome of this step

After successfully completing the TOS Flow using the Account Ticket Id, the account, property, and view (profile) will be created. The user will now have an active account. The response from the TOS page will include the Account ID, Property ID, and View (Profile) Id.

The technical flow for this step

Using the Account Ticket Id, redirect the user to the Google Analytics TOS page where they can accept the TOS, then you need to handle the response from the API.

Form the TOS URL for the user to visit

Redirect the user to the TOS page and include the Account Ticket Id as part of the URL:

https://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?
  api.accountTicketId={account_ticket_id}
Handle the TOS response

After the user takes some action on the TOS page then they will be redirected back to the redirectUri specified during account ticket creation. The response from the TOS page will be included as part of the query string.

Successful responses will return data about the newly created account structure as well as the original accountTicketId:

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

For example, if the TOS handler for your application is at http://www.your-app.com/gaTOS then this should be set as the redirectUri when creating account tickets. Your application's TOS handler should expect and properly handle HTTP GET requests that contain accountId, webPropertyId, profileId and accountTicketId query parameters for cases when the account ticket is valid and the user has accepted the TOS.

Unsuccessful responses will include the error response:

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

Your TOS handler should also properly handle HTTP GET requests that contain an error query parameter, indicating something went wrong. The value of the query parameter can be used to take further action or display a message to the user:

  • error=user_cancel - The user did not accept the terms of service.
  • error=max_accounts_reached - The user has reached the Google Analytics account limit.
  • error=backend_error - A general error. The server returned an error not in the above categories.

4. (Optional) Integration Opportunities

If you’ve followed the Technical Flow above then you will have created an account for the user and will have the Account Id, Property Id, and View (Profile) Id. If you also requested additional permissions you may also have a refresh token for the user. With this data you can:

User Flow

This section describes the implementation considerations related to the steps of the account creation flow from the perspective of the user.

The flow starts with the user offered the following 2 options to enable analytics for their property:

  1. Create a Google Analytics Account
  2. Use an existing Google Analytics account. (Note: This flow is not covered in this document. See the Management API for details on how to access a user's Google Analytics configuration data.)

When creating a new Google Analytics account there is information that you're required to send with the provisioning request such as account name, property name, etc. Depending on the information you have about the user and the preferred flow you'd like to show them there are 3 main options for initiating the user flow after the user clicks on 'create account':

Ask for account details after authorization

In this case the user is asked for account details in the middle of the process. The flow would look similar to the following:

  1. User is redirected to Google Account Service for OAuth 2.0 flow. If user does not have a Google Account or is not signed-in they will be asked to create a Google Account or sign-in.
  2. User is prompted to authorize the application to ‘Create Google Analytics Accounts’.
  3. User accepts permissions request for the application.
  4. User is redirected to Service Provider. Note that if the user denies authorization then they are still redirected back to Service Provider.
  5. A form is presented to the user to collect details about the account to create (e.g. Account name, property name, profile name, timezone, website URL, etc.)
  6. User fills out and submits form and is redirected to Google/shown the Google Analytics Terms of Service (TOS).
  7. User accepts the TOS.
  8. User is redirected to Service Provider and is shown some success message that they have successfully created a Google Analytics account with details about the account and how to access it. Note that if the user does not accept the TOS they are still redirected back to Service Provider.

Ask for account details before authorization

In this case the user is asked up front for configuration details of the account about to be created. The flow would look similar to the following:

  1. On Service Provider site, a form is presented to the user to collect details about the account to create (e.g. Account name, property name, profile name, timezone, website URL).
  2. User fills out the form, clicks submit and is redirected to Google Account Service for OAuth 2.0 flow. If user does not have a Google Account or is not signed-in they will be asked to create a Google Account or sign-in.
  3. User is prompted to authorize the application to ‘Create Google Analytics Accounts’.
  4. User accepts requested permissions for the application.
  5. User is redirected to Service Provider.
  6. User is redirected to Google/shown the Google Analytics Terms of Service (TOS).
  7. User accepts the TOS.
  8. User is redirected to Service Provider and is shown some success message that they have successfully created a Google Analytics account with details about the account and how to access it.

Prefill account details or skip forms

If information about the user account is already available (e.g. website URL, website name, timezone, etc.) then both options above can be further simplified by:

  • Pre-filling the form and allowing the user to edit if they want
  • Skipping the form step altogether and automatically creating the account using the existing information.