In this article
We provide details on the Freewheel integration and a walkthrough to enable this feature.
FreeWheel is a popular ad server for media companies who have significant proportions of video content and ad inventory. In particular, it supports video ad serving across a range of environments making it highly suitable for broadcasters and multimedia companies.
This release provides a native integration with FreeWheel ad server for the purpose of activating Permutive cohorts and making these available in the FreeWheel UI for campaign targeting.
The FreeWheel activation utilises cohort IDs that are made available client-side as key-value pairs that can be appended to the FreeWheel ad request for targeting. This activation is available in any environment where Permutive is deployed via an SDK or the CCS API and FreeWheel ad requests are being sent.
Note: This activation does not currently support any native event collection (as with GAM slotViewable or slotClicked events)
The FreeWheel integration requires involvement from your FreeWheel technical account manager in order to provision access to the Audience Item API.
- Contact your Permutive Customer Success Manager to request the FreeWheel integration. You will need to provide:
- Your FreeWheel network code
- Your FreeWheel technical account manager
- Permutive will provide a unique email alias to the FreeWheel technical accounts team. This is required to enable Audience Item API authentication
- After Permutive has received confirmation that the alias has been enabled, we will need your username and password for the API so Permutive can enable the integration. Typically credentials are provided for a staging environment first, Permutive enables the integration, and you are able to test the integration. Once you are ready to run the integration in production, the production username and password should be shared with Permutive and Permutive will update the credentials for the integration so it can run in production.
When the FreeWheel integration is enabled, a new localStorage and activation key will be created. The freewheel key includes all of the cohort IDs for a given user that have been activated to FreeWheel.
The following are the local storage keys that will contain the Permutive cohorts that are activated to Freewheel:
web, HbbTV, Tizen - _pfws (note for the web environment we have some examples of how to append the cohorts to the ad requests, see here)
tvOS, iOS - freewheelCohorts
AndroidTV, FireTV, Android - freewheelAct
Note: Customers will be responsible for retrieving cohort IDs from local storage, the SDK or the CCS API response and appending these to the FreeWheel ad request.
There are two main methods for activating cohorts within the Permutive platform. In each instance, you must turn on the FreeWheel activation for each cohort that you intend to make available within the ad server.
Important: FreeWheel does not accept two audiences with the same name. If you encounter an error when activating a cohort to FreeWheel, check to see if you already have an audience in your FreeWheel network with the same name as the one you are trying to use.
To send cohorts via the FreeWheel Activation Sync within the cohort builder, follow these steps:
In the Permutive Dashboard
- Login to your project and create a new cohort or open the builder for an existing cohort
- Once you have finished defining or updating your cohort, at the end of the cohort builder you'll find the Activation sync: 👉
- Switch it on (so it turns green) and save the cohort.
Your cohort will now be sent to FreeWheel an Audience Item which can be applied to campaigns for targeting.
You can also send cohorts manually via the FreeWheel Activation.
In the Permutive Dashboard:
- Login to your project, select 'Cohort Activation' *→ '*Add Activation'
- Select the FreeWheel Action
- Set up the activation for your cohort. For more guidance on setting up activations, see this guide.
- Choose the cohort you'd like to activate to FreeWheel
- Hit 'Save'
Cohorts activated to FreeWheel are represented as ‘audience items’ within the FreeWheel UI. In order to target a Permutive cohort for a campaign / line item you must:
- Navigate to the ‘Audience’ section of the line item
- Search for the audience item by name using the search function provided
- Choose whether to include or exclude the audience item from being targeted for your campaign