Google Ads Integration

Applicable to SA3.0.4 and above.

This feature is controlled by a separate license. Please contact your account manager if you require it.

If your app is running ad campaigns overseas to acquire new users, and you want to retrieve aggregated ad data (such as impressions, clicks, and cost) from overseas advertising platforms into the Sensors Data platform, you can use this feature.

Overview

It supports integration with Google Ads, enabling the retrieval of ad-level data such as impressions, clicks, and cost via its OpenAPI. The retrieved data is then stored in Sensors Data as events, allowing for analysis within the analytics model. It can also be correlated with downstream user behavior data for further analysis.

Feature Entry

Channel Tracking > Third-Party Data Integration > Advertisin > Google Ads

Instructions

Google Ads Data Explanation

It supports retrieving ad data for four ad levels via the Google Ads API. For details, please refer to the official documentation: Google Ads API Official Documentation

4 built-in templates are as follow, covering commonly used advertising metrics and dimensions.

• Ad Group Ad Template: Ad-level advertising data. The original content can be found in the official documentation . The metrics and dimensions obtainable through this template are as follows:

metrics

metrics.all_conversions metrics.all_conversions_value metrics.active_view_impressions metrics.active_view_cpm metrics.active_view_ctr metrics.impressions metrics.clicks metrics.conversions metrics.cost_micros metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.average_cost metrics.average_cpc metrics.average_cpe metrics.average_cpm metrics.average_cpv metrics.ctr metrics.value_per_all_conversions metrics.value_per_all_conversions_by_conversion_date metrics.value_per_conversion metrics.value_per_conversions_by_conversion_date

group by

customer.id customer.status customer.time_zone customer.currency_code campaign.id campaign.name campaign.status campaign.app_campaign_setting.app_id campaign.advertising_channel_type campaign.advertising_channel_sub_type ad_group.id ad_group.name ad_group.status ad_group.type ad_group_ad.ad.id ad_group_ad.ad.name ad_group_ad.ad.type ad_group_ad.status segments.date segments.ad_network_type segments.slot

• Campaign Template: Ad data at the Campaign level. The original content can be found in the official documentation . The metrics and dimensions obtainable through this template are as follows:

metrics

metrics.all_conversions metrics.all_conversions_value metrics.active_view_impressions metrics.active_view_cpm metrics.active_view_ctr metrics.impressions metrics.clicks metrics.conversions metrics.cost_micros metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.average_cost metrics.average_cpc metrics.average_cpe metrics.average_cpm metrics.average_cpv metrics.ctr metrics.value_per_all_conversions metrics.value_per_all_conversions_by_conversion_date metrics.value_per_conversion metrics.value_per_conversions_by_conversion_date metrics.view_through_conversions metrics.current_model_attributed_conversions metrics.current_model_attributed_conversions_value

group by

campaign.id campaign.name campaign.status campaign.campaign_group campaign.app_campaign_setting.app_id campaign.advertising_channel_type campaign.advertising_channel_sub_type segments.date segments.ad_network_type customer.id customer.status customer.time_zone customer.currency_code

• Geographic View Template: Ad data at the Geographic level. The original content can be found in the official documentation . The metrics and dimensions obtainable through this template are as follows:

metrics	metrics.all_conversions metrics.all_conversions_value metrics.average_cost metrics.average_cpc metrics.average_cpm metrics.average_cpv metrics.ctr metrics.clicks metrics.conversions metrics.conversions_value metrics.cost_micros metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.impressions metrics.interactions
group by	customer.id customer.status customer.time_zone customer.currency_code campaign.id campaign.name campaign.status ad_group.id ad_group.name ad_group.status ad_group.type segments.ad_network_type segments.date geographic_view.country_criterion_id geographic_view.country_name geographic_view.location_type geographic_view.resource_name

• Conversion Action Template: An ad template for conversion actions. The original content can be found in the official documentation . The metrics and dimensions obtainable through this template are as follows:

metrics	metrics.all_conversions metrics.all_conversions_value
group by	customer.id customer.status customer.time_zone customer.currency_code conversion_action.app_id conversion_action.id conversion_action.mobile_app_vendor conversion_action.name conversion_action.origin conversion_action.owner_customer conversion_action.type segments.date

• Keyword Template：An ad template for keyword level。The original content can be found in the official document。The metrics and dimensions obtainable through this template are as follows: （Applicable to SA305 ）

metrics

metrics.all_conversions metrics.all_conversions_value metrics.active_view_impressions metrics.active_view_cpm metrics.active_view_ctr metrics.impressions metrics.clicks metrics.conversions metrics.cost_micros metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.average_cost metrics.average_cpc metrics.average_cpe metrics.average_cpm metrics.average_cpv metrics.ctr metrics.value_per_conversion

group by

customer.id customer.status customer.time_zone customer.currency_code customer.manager campaign.id campaign.name campaign.status campaign.app_campaign_setting.app_id campaign.advertising_channel_type campaign.advertising_channel_sub_type ad_group.id ad_group.name ad_group.status ad_group.type ad_group_criterion.criterion_id ad_group_criterion.keyword.text keyword_view.resource_name segments.date segments.ad_network_type

 

Preparation Before Integration

You need to complete authorization and authentication with Google Ads before you can retrieve ad data through the Google Ads API. For details, please refer to the official documentation: Google Ads API Official Documentation

To make a Google Ads API call, you should prepare information as follows.

Google Ads Manager account : You need a Google Ads Manager account to apply for the Google Ads API.

Developer Token : This token allows your app to connect to the Google Ads API. Each developer token is assigned an API access level, which controls the number of API calls you can make per day and the environments in which you can make those calls. Obtaining a Developer Token: A developer token is a 22-character alphanumeric string that allows your app to connect to the Google Ads API. After Google assigns you a token, you can view it or create a new one on the API Center page of your Google Ads Manager account.

OAuth 2.0 Credentials (Client & Secret) : The Google API Console project generates OAuth 2.0 credentials for your app. Your app then uses these credentials to authenticate users and obtain their authorization to manage their Google Ads accounts. This authorization is later used by your app to make API calls to the Google Ads accounts. 

Google Ads account (Advertiser account) : This is the account you will be making API calls to. You need to have permissions for the account, such as the ability to retrieve reports or modify campaigns. You also need the 10-digit account number of the account you are making API calls to. In the Google Ads web interface, this value is displayed as 123-456-7890. This account number is passed as a parameter to the Google Ads API call, but without the hyphen: 1234567890.

Step	Content	Description
Step 1	Create a Google Ads Manager Account	See official documentation for reference.
Step 2	Apply for a Developer Token using your Google Ads Manager account	Log in to your Google Ads account using your Google Ads Manager account, select Admin - API Center in the left. Fill out the form and complete the Developer Token application.
Step 3	Obtain application credentials, i.e., the Client ID and Secret	Log in to Google Cloud Platform. 1. Create a project. Then select API & Services and Enable APIs and services. After navigating to the API Library, search for Google Ads and enable it. 2. Go to Credentials, select Create credentials, and choose OAuth client ID from the drop-down menu. You need to configure the Consent Screen first. Click Configure to go to the Branding page, and then click Get started to begin configuration. 3. When creating a Client, select Web application as the Application Type and fill in the Authorized redirect URIs. You can fill in any address here first, and then replace it with the address provided in the Sensors Data later. 4. Go to Audience in the left navigation bar, then click Publish App.
Step 4	Grant Google Ads API access	After successfully creating the client ID, navigate to Data Access in the left navigation, add the scopes that the client is allowed to access, search for Google Ads API, and add it.
Step 5	Link your Google Ads Manager account with your Google Ads advertiser account	Log in to Google Ads using your manager account, select Accounts in the left navigation bar, then select Sub-account settings, click +, select link existing account, fill in the information, and a verification link will be sent to your Google Ads advertiser account. Log in with your Google Ads account, select Admin in the left navigation bar, then select Access and security, then the Managers tab. You will see the verification request sent in the previous step; select Accept. The Manager will then be able to access this ad account.

Configure Google Ads Integration

The configuration mainly includes the following three parts:

1. Basic Information

2. Authorization Configuration

The fields in this section are primarily used for authentication with Google Ads and to specify the scope of ad accounts to be retrieved. Please refer to the "Preparation Before Integration" section in the previous to obtain the relevant fields from the Google Ads platform.

A maximum of 100 Google Ads accounts are supported per integration plan and A maximum of 10 intergation plans can be created.

Client ID must be unique across all projects. If a duplicate message is displayed, check if the same Client ID exists in different projects.

Upon re-editing, the Client ID cannot be modified. 

3. Data Retrieval Configuration

After clicking "Confirm Creation," you need to complete the authorization process with Google Ads. The authorization process includes the three steps shown in the image below.

Clicking the blue "Go to Authorization" link to be redirected to the Google Ads authorization page. Log in with your Google account. (Note that you need to log in with the Google account that created your Google Manager account). Since Google's verification process was not completed when publishing the app in Google Cloud Console, a warning message will appear indicating that the app is insecure. Click "Advanced" and select "Continue."

After completing the above steps, select "Authorization Completed" in the Sensors Data pop-up window. If the authorization fails, an error message will be displayed.

Once the plan is successfully created, Google Ads data will be retrieved daily according to the template content.

Data Retrieval

Data retrieval is supported, you can select a time period of up to 180 days to retrieve ad data.

Data Storage Instructions

The retrieved Google Ads data will be uniformly stored as events. The original fields will be standardized and stored as attributes prefixed with "sensors_ad".

Note:This data will be counted against your event quota.

These events will use a fixed value as their user identifier, effectively representing a virtual user.

The events corresponding to different templates are as follows:

Ad Group Ad Template: google_ads_ad_group_ad

Campaign template: google_ads_campaign

Geographic View template: google_ads_geographic

Conversion Action template: google_ads_conversion_action

The following lists some common raw data and their corresponding event properties:

Original field	Event properties
customer.id	sensors_ad_customer_id
customer.time_zone	sensors_ad_customer_timezone
customer.currency_code	sensors_ad_customer_currency
media_source	sensors_ad_media_source​
campaign.id	sensors_ad_campaign_id
campaign.name	sensors_ad_campaign_name
ad_group.id	sensors_ad_ad_group_id
ad_group.name	sensors_ad_ad_group_name
ad_group_ad.ad.id	sensors_ad_ad_id
ad_group_ad.ad.name	sensors_ad_ad_name
segments.date	sensors_ad_segments_date
geographic_view.country_name	sensors_ad_country
metrics.all_conversions	sensors_ad_metrics_all_conversions
metrics.impressions	sensors_ad_metrics_impressions
metrics.clicks	sensors_ad_metrics_clicks
metrics.cost_micros	sensors_ad_metrics_cost

How to Analyze

You can select the corresponding event in Event Analysis to analyze metrics such as Google Ads impressions, clicks, and cost.

Permissions

By default, administrators can configure Google Ads integration plans. They can also assign permissions for configuring and viewing plans to standard users.