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 how to access 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:
- Register your application in the Google API Console.
- Authorize to create a new Google Analytics account.
- 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:
- Prompt user to authenticate and authorize the application/service using OAuth 2.0.
- Create an Account Ticket using the Provisioning API.
- Redirect the user to accept the Google Analytics Terms of Service (TOS) and handle the response.
- (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
- Client ID - The
Client ID
of the project you will be using. This is available from the Google Developers Console. Read about the OAuth 2.0 Web Server flow to learn more. - Redirect URI - This is where the user is redirected to
and the OAuth 2.0 response is sent.
- Configure
Redirect URIs
and obtain theClient ID
for your project using the Google Developers Console. - The value of this parameter must exactly match one of the values registered in the Google Developers Console (including the http or https schemes, case, and trailing '/').
- Configure
- Auth Scope for Google Analytics Provisioning API
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 their 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
oredit
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.
- A
- Web Property fields
- A
name
property is required for the property. - A
websiteUrl
is required.
- A
- Profile fields
- A
name
property is required for the profile. - A
timezone
can optionally be provided. Default isAmerica/Los_Angeles
.
- A
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://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{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:
- If applicable, automatically inject the standard Google Analytics tracking snippet with the Property Id of the newly created account for each page on the user's website.
- Automatically configure the user's Property using the Management API.
- Provide reports for the user within your product (e.g. in the admin panel) using the Embed API or the Core Reporting API.
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:
- Create a Google Analytics Account
- 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:
- 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.
- User is prompted to authorize the application to ‘Create Google Analytics Accounts’.
- User accepts permissions request for the application.
- User is redirected to Service Provider. Note that if the user denies authorization then they are still redirected back to Service Provider.
- 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.)
- User fills out and submits form and is redirected to Google/shown the Google Analytics Terms of Service (TOS).
- User accepts the TOS.
- 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:
- 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).
- 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.
- User is prompted to authorize the application to ‘Create Google Analytics Accounts’.
- User accepts requested permissions for the application.
- User is redirected to Service Provider.
- User is redirected to Google/shown the Google Analytics Terms of Service (TOS).
- User accepts the TOS.
- 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.