Consent management

Overview

OpenTV Video Platform is integrated with Didomi for consent management.

A client application integrator must take the following steps to ensure that the end user is able to consent (or not) to their data being used for various purposes:

Integrate the Didomi SDK into your application.
See the Didomi developer documentation for more details.
In the Didomi console:
1. Add the required purposes with the appropriate choice of vendors.
2. Get the purpose ID of each purpose and use it in the custom JSON to specify the ordering of the purposes.
See Order of purposes in the Didomi preferences popup customisation documentation.
Use the SDK to get the consent choices and display them to the user.
The consent categories are explained in Consent categories, below.
Use the SDK to send the user account’s unique ID to Didomi so that the user’s consent choices can be synced across all the devices associated with the account.
Use the SDK to send the user’s choices to Didomi.
Get the user’s choices from Didomi using the SDK and then call the UAV activity endpoint to send their choices to OpenTV Video Platform.
Use the user’s choices to create a consent mask (where each bit represents the user’s choice for a pre-agreed purpose). The client app must store this mask.
Send this consent mask as metadata every time the app records activity using the UAV activity reporting endpoint.
See Reporting activity and event metrics to UAV.
Send this consent mask as a header in requests to URL Builder to get the playout URL. See Get the playout parameters.
(The user’s advertising-related consent choices affect how URL Builder constructs the URL.)

These are explained in detail in the sections below.

Notes

There are certain uses of user data (“legitimate interest” categories) that the user may not opt out of (for example, those to do with fraud prevention, authentication and authorisation, and so on).

If the user does not consent to the “legitimate interest” options, they will not be able to use the service.

Consent categories

The consent categories used by OpenTV Video Platform are explained in the following table:

Category	Purpose	Legitimate interest?	Notes
Service operation	Fraud analysis and revenue protection	Yes
	Authentication and authorisation	Yes
	Processing of payments for access to platform features and content	Yes
	Provisioning of video platform, DRM, and content to enable consumers to view content	Yes
	Customer service operations	Yes
	Use limited data to monitor content usage	Yes (usage depends on other consents agreed to in the popup)	The following activities fall into the “legitimate usage” category: Bookmarks Viewing history `playbackPause` `playerError` `genericError` `playbackSkipAhead` `playbackSkipBack` `playback_metrics` `privacyPolicy` `downloadTriggered` (not sent from client app) `scheduleRecording` (not sent from client app)
	Audience measurement	No	If the user opts out of this category, the client app must not report the following activities to UAV: `thirdPartyAppStart` `returnToLauncher` `deepLinkTriggered` `appStart` `appEnd` `adWatched` `adDelivered` `adSkipped` `railView` `railSelection`
Service personalisation	Service features to personalize viewing experience Analysis of user behaviour to provide personalized and account level recommendations for features and content to consume	No	If the user opts out, the client app must still report the relevant events from the above lists (assuming the user has opted in to the above; if they have not, the client will not report any of these event). However, they will not be passed to the recommendation engine.
Advertising	Various options as defined by Transparency & Consent Framework (TCF) standards	No	Depending on the user’s consent choices (as passed in the consent mask), URL Builder will insert or omit the relevant advertising-related parameters when constructing playout URLs.
Advertising	Server-Side Ad Insertion (SSAI)	No
Marketing	Marketing via electronic means	No	If the user opts in for electronic means communication, the consent is applied to the push messaging feature of OPF. There are two types of push messaging that originate from OPF towards users' devices: Mandatory service events like EAS notifications and EPG metadata updates Marketing or communication outreach The consent provided here is only applied to marketing or communication outreach.
Marketing	Marketing via physical means	No

Prerequisites

The consent choices that will be presented to the user must already be configured in the Didomi console. This can be done by NAGRAVISION or by the operator, depending on the type of deployment.

Sending the unique account ID to Didomi

Every user account has an ID that is globally unique. This must be provided to Didomi so that the user’s consent choices can be synced across the devices associated with the account.

Get the unique account ID from ADM by making a GET request to:
CODE
```
https://<server>:<port>/adm/v1/user/accounts
```
Find the value of the sharedConsentPublicId field in the response.
Send this ID to Didomi by passing it as the organization-user-id parameter to the Didomi SDK’s setUser() method, as explained here.

Sending the user’s consent choices to UAV

Once the client application has displayed the consent options to the user and they have made their choices, the application must send the results to UAV.

Request

To do this, it should send a POST request to:

CODE

http://<host>:<port>/useractivityvault/v1/useractivity/privacyPolicy

Headers

Content-Type: application/json
Authorisation

Mandatory arguments

accountId
userId – must be set to "" (empty string)
deviceId
key – must be set to "" (empty string)
timestamp – the activity timestamp in <YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>Z format
metadata – the metadata block must include the following:
- consentForTargettedAd
- policyConsentGiven
- policyType
- policyShown
- policyRead
- policyString
- dateTimeDevice
- consentProvider – the consent provider, in this case Didomi
- consents – a block detailing the user’s consent choices ( the consents array from Didomi callback ).
  - The exact parameters that are required will depend on what has been configured in Didomi. An example of what is returned by Didomi is provided below.

consent block example

JSON

{
  "consents": [
    {
      "purpose": "marketing-mLX9fGpr",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "improve_products",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "create_ads_profile",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "select_personalized_ads",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "select_basic_ads",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "measure_ad_performance",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "measure_content_performance",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "create_content_profile",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "select_personalized_content",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "device_characteristics",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "market_research",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    },
    {
      "purpose": "cookies",
      "vendors": [
        {
          "id": "google",
          "status": true
        },
        {
          "id": "c:googleana-4TXnJigR",
          "status": true
        },
        {
          "id": "c:testnagra-f2YDfbXq",
          "status": true
        }
      ]
    }
  ]
  }

Response

A successful request returns an HTTP 202 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

Creating the consent mask

The client application must create a consent mask from the user’s choices. It must store this mask and sent it in the metadata section of the request every time it calls UAV’s activity reporting endpoint.

The mask is a string made up of ones and zeroes, each bit representing a specific, pre-agreed user choice.

A good way to determine the order of these digits is to use the Didomi.getConfig() method to get the ordered list of consent items.

Include the mask in the request metadata as a key/value pair with consentMask as the key.

Example

You could have a three-character consent mask, where the three characters correspond to the following categories:

First character: mandatory events
This must always be included and set to 1.
Second character: service/usage personalisation
Events are stored or processed for personalised services.
Third character: recommendation engine
Events are forwarded to the recommendation engine.

With this arrangement, the following combinations of characters are possible for the value of contentMask:

"100": only mandatory events
"110": mandatory + service/usage personalisation
"101": mandatory + recommendation engine
"111": all categories (mandatory, service/usage personalisation, and recommendation engine)

When reporting events to UAV, the client application should include contentMask like this in the metadata section of the request payload:

JSON

"contentMask": "111"

If the client application does not send the content mask in its activity reporting requests (for example, if the user is running an older version of the app that does not send this data), OpenTV Video Platform treats the request as if the user has opted out of all but “legitimate interest” options.