Integrate Rayn JS with Google Publisher Tag
The Google Ad Manager integration for Rayn JS can help you activate Rayn data in GAM. This guide will help you understand the options and inner workings of this integration.
How to enable Google Ad Manager integration for Rayn JS
Open the RaynJS connection you wish to enable and select the Integrations tab. Enable the toggle for Google Ad Manager. Once enabled you can click on Edit to select the taxonomies you wish to use (Personas are always used).
Google Ad Manager Integration details
Google Ad Manager Integration details
When the GAM integration is enabled on the applicable RaynJS connection, RaynJS will push content categories and cohorts to the Google Publisher Tag (GPT) on the pages where it's implemented.
The current high level operational sequence of RaynJS is as follows:
RaynJS loads.
Establishes consent (in the case of a TCF CMP).
Checks local storage for content categories:
If no Rayn data is present in local storage, then RaynJS will attempt to retrieve categories from the API endpoint. (Retrieving data from cache typically occurs within 50ms, depending on CDN edge cache and proximity to the edge location.)
If no categories are present in the Rayn cache, we will consider the content to be new and process it for contextualization, which will take approximately 30 minutes.
RaynJS calls window.googletag.pubads().setTargeting to set the key values.
Timing optimization
Timing optimization
When using RaynJS to connect to GPT it is advisable to ensure that RaynJS has enough time to set targeting data in GPT before the ad request is made. Consider using event based requests. See this article for more background.
TargetingSet event
For event based loading RaynJS will emit an event once the setTargeting operation is completed. Example:
window.addEventListener("message", (message) => {if (message.data.raynJSReturn) {console.log("RaynJS message: ", message.data.raynJSReturn);if ("targetingSet" in message.data.raynJSReturn) {// message.data.raynJSReturn.targetingSet is boolean, true if raynJS has set targetingconsole.log(`RaynJS set targeting: ${message.data.raynJSReturn.targetingSet}`);}}});
Synchronize taxonomies with Google Ad Manager
Rayn data is made available via key-values that are targetable in Google Ad Manager (GAM). In GAM, you must set up key-values to allow targeting on Rayn Personas, Contextual Categories, and Audience Cohorts. Key-values can be created manually or automatically via key-value sync. This allows all personas, content categories, and audience categories from your taxonomies to be synchronized as key-values to GAM.
Setup and Manage Key-Values
There are two ways you can work with key-values: via automatic sync or by creating them manually. We recommend the automatic sync so you can save time and implement more efficiently.
Automatic Taxonomy Sync Details
Automatic Taxonomy Sync Details
Automatic key-values sync allows you to synchronize all categories (personas, content categories and audience cohorts) as key-values to GAM. Rayn will ensure that all categories are represented as values in GAM using API access. The sync will:
Create the following keys (if they do not exist yet):
Rayn_Context_2.2 - IAB content taxonomy 2.2
Rayn_Context_3.0 - IAB content taxonomy 3.0
Rayn_Cohorts - IAB audience taxonomy 1.1
Rayn_Personas - Rayn Personas
Create and synchronize predefined values under the keys mentioned before for all categories.
Remove the values once a category is removed from the taxonomy
Set up taxonomy sync
Step 1 - Provide Rayn Access to Google Ad Manager
Sign in to Google Ad manager.
Navigate to Admin > Global settings > Network settings.
Make sure the "API access" toggle is enabled.
Click Add a service account user.
Enter the following service account email: [email protected]
Grant appropriate permissions to the service account. The required permissions are:
- View ad units, placements, and labels
- Edit ad units, placements, and key-values
- Edit key-values values
Click Save. A confirmation message should display, confirming the addition of your service account.
Step 2 - Enable the taxonomy sync in Console
Retrieve the Ad Manager network code from GAM. See Google's article "Find Ad Manager account information" to learn how.
In Console, go to Connections and open the Rayn JS connection you wish to enable and select the Integrations tab.
Click the "Edit" button next to the Google Ad Manager integration and add your GAM network code in the provided field.
Switch on the toggle to enable the GAM Sync. Rayn will now keep all personas and taxonomies in sync with the respective keys in GAM. It may take a few minutes for the first values to appear in GAM.
Are you running more than one site in your Google Ad Manager account, and do you have multiple Rayn JS configurations? Then you will only need to set up the taxonomy sync for one of them.
When the sync is disabled or the integrations is disabled then Rayn will remove the values from GAM.
Working with Google Ad Manager
How to include Key-Values in GAM Reporting
How to include Key-Values in GAM Reporting
The values of automatic key-values sync are excluded in GAM reporting by default. If you want to add them to reporting, you can change this setting on GAM. See how the key-value setting looks like by default below:
Note that Google account limits are lower for reportable key values. To learn more about key-values reporting and how to mark the key-value as reportable, see Google's article "Report on key-values".
Manage Key-Values Manually
Manage Key-Values Manually
In case you do not want Rayn to synchronize the categories automatically, then it is also possible to either pre-define the deals manually, or use the dynamic option.
Sign in to Google Ad Manager.
Navigate to Inventory > Key-values.
Click New key-value.
Enter "Rayn_Personas" in the Name field.
Set the Value type as Dynamic.
Configure the other settings to your preference.
Click Save.
Add a Line Item with Custom Targeting
Add a Line Item with Custom Targeting
When creating a line item that is targeting Rayn data, you must set up custom targeting with the key-value you have generated/created. In the "Custom targeting" section under "Add targeting", select one or more values under the keys “Rayn_Context_2.2”, “Rayn_Context_3.0”, "Rayn-Cohorts" or "Rayn_Personas".
To learn more about adding new line items, see Google's article "Add new line items".