CTV Implementation Overview

Suggest Edits

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.

  1. Create a new deployment plan by navigating to Experience Server -> Deployment plans and clicking the Create Plan button.

    1. Name the plan ctv, select the desired Theme to use, and click Next.
    2. For each Jurisdiction,
      - Select No Experience for Consent & Disclosure Experience.
      - Select the desired experience for Preference Experience.
      Click Next.
    3. Select a document for each Document Type and click Save & Finish

  2. Create a new property for CTV.

    1. Navigate to Experience Server -> Properties.
    2. CTV
      1. Click 'Create Property`.
      2. Name the property and code CTV and ctv respectively.
      3. Set the Property Type to CTV.
      4. Click Next.
      5. Leave the environment name production, set the pattern to .*, set the domain to the url for the page hosting the Ketch Preference Center.
        6 . Click Next.
      6. Ensure Ketch Managed Cookie is disabled.
      7. Toggle Custom Identity Spaces on.
      8. Set Location to Querystring, Identity Space to <custom_identifier>, Name to <custom_identifier>, and Format to String.
        Note: add any addition identity spaces you will be capturing for this property.
      9. Click Save & Finish.
      10. Click Manage Deployment, select the production environment, and the ctv deployment plan.
      11. Click Deploy.

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
  • includeswb_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