CTV Implementation Overview
Ketch's recommended approach to updating a users preferences from a connected television (CTV), or over-the-top (OTT) platform, is to display a QR code to direct the user to a web page where they can update their preferences.
Ketch Platform Configuration
To ensure the Ketch Smart Tag presents the correct behavior, it is recommended to go through the Basic Ketch Implementation Guide.
Once the platform has been initially configured, you'll need to make a few adjustments for a CTV/OTT implementation.
-
Create a new
deployment plan
by navigating toExperience Server -> Deployment plans
and clicking theCreate Plan
button.- Name the plan
ctv
, select the desired Theme to use, and clickNext
. - For each Jurisdiction,
- SelectNo Experience
for Consent & Disclosure Experience.
- Select the desired experience for Preference Experience.
ClickNext
. - Select a document for each
Document Type
and clickSave & Finish
- Name the plan
-
Create a new
property
for CTV.- Navigate to
Experience Server -> Properties
. - CTV
- Click 'Create Property`.
- Name the property and code
CTV
andctv
respectively. - Set the Property Type to
CTV
. - Click
Next
. - Leave the environment name
production
, set the pattern to.*
, set the domain to the url for the page hosting the Ketch Preference Center.
6 . ClickNext
. - Ensure
Ketch Managed Cookie
is disabled. - Toggle
Custom Identity Spaces
on. - Set
Location
toQuerystring
,Identity Space
to<custom_identifier>
,Name
to<custom_identifier>
, andFormat
toString
.
Note: add any addition identity spaces you will be capturing for this property. - Click
Save & Finish
. - Click
Manage Deployment
, select theproduction
environment, and thectv
deployment plan. - Click
Deploy
.
- Navigate to
Obtaining the QR Code
To obtain a QR code for a user, perform a GET on the following URL with your organization code, the property code created above, and the querystring parameters : https://global.ketchcdn.com/web/v2/qr/<ORGANIZATION_CODE>/<PROPERTY_CODE>/preferences.png
querystring parameters (with defaults provided):
env=production
lang=en-US
size=256
(max 4096)bgcolor=ffffff
(will leverage Ketch Theme, if available)fgcolor=000000
(will leverage Ketch Theme, if available)path=/preferences-page.html
(path to the page which will present the Ketch Preference Center)swb_show=preferences
<user_identifier1>=<unique_identifier>
<user_identifier2>=<unique_identifier>
- etc....
Note: all querystring parameters are optional,
- except there must be at least 1 user identifier, it must be unique, and must be one of the identities on the property
- include
swb_show=preferences
, if the Preference Center is not already being opened by the page being link to by the QR code.
The generated QR code will be a dynamically created link using the domain
set in the environment
section of the property created above, path
, if provided, with the querystring parameters containing swb_show
parameter and all user identities provides.
example QR code generation
https://global.ketchcdn.com/web/v2/qr/<ORGANIZATION_CODE>/<PROPERTY_CODE>/preferences.png?path=/preferences-page.html&swb_show=preferences&rida=e0bfd19e-6de3-4301-876c-3c46100315aa
example generated link
https://yourcompany.com/preferences-page.html?swb_show=preferences&rida=e0bfd19e-6de3-4301-876c-3c46100315aa
Displaying the Ketch Preference Center
The swb_show
parameter placed on the QR code will automatically trigger the launching of the Ketch Preference Center on the referenced page.
The Ketch Smart Tag will pull all values for all identities defined on the property from the querystring. The preference center will show the users current preferences, allowing the user to update their preferences accordingly. If the user has not previously set their preferences, the default preferences for the users current jurisdiction will be shown.
Retrieving CTV stored user consent preferences
Ketch recommends retrieving a users consent options during the following lifecycle events of your application
- start up
- wake up
- navigation away from update preferences page
The following call, with corresponding body parameters, can be made to the Ketch Platform to retrieve the latest consent preferences for a user.
POST https://global.ketchcdn.com/web/v2/consent/<ORGANIZATAION_CODE>/get
{
"propertyCode": "<PROPERTY_CODE>",
"environmentCode": "production",
"identities": {
"rida": "e0bfd19e-6de3-4301-876c-3c46100315aa",
...
}
}
RESPONSE
The response contains the purpose codes defined within the Ketch Platform and the users corresponding consent preference.
{
"purposes": {
"<PURPOSE_CODE>": "<PREFERENCE_VALUE>",
"<PURPOSE_CODE>": "<PREFERENCE_VALUE>",
...
}
}
SAMPLE RESPONSE
{
"purposes": {
"analytics": "true",
"email_marketing": "true",
"essential_services": "true",
"targeted_advertising": "true"
}
}
Updated 4 months ago