OTT fingerprint integration

1. Summary

The (25.10) Secure Session Manager (SSM) serves as a fingerprint messenger, notifying the client to activate fingerprint functionality.

In order to generate a fingerprint token with SSM, a fingerprint ID and fingerprint Group IDs must be included in the Content Authorization Token (ContentAuthZ).
- The fingerprint ID is the visual ID that will displayed on the screen.
- The fingerprint Group IDs are the groups the device belongs to. This is free text, for example, this can be “STB” “TV” or “West Coast”. It is also recommended to have a group that contains only the device. This allows, if targeting only this device to quickly update the campaign definition by limiting the targeted group to this one.
The session setup interface initializes the session and creates the initial Fingerprint token including potentially a Fingerprint campaign trigger.
The heartbeat operation renews the Fingerprint tokens and retrieves the next Fingerprint campaign(s).
The Fingerprint token embeds the active Fingerprint campaigns for the content being currently watched included within the session duration (5 minutes by default).

Based on the fingerprint Group IDs and the content ID, SSM retrieves the corresponding campaigns defined in advance in the(25.10) ISPM API Reference.

Fingerprint campaigns are defined at channel level. A campaign includes the settings (fingerprint profile), a start and an end date and the groups that are targeted.
A channel and a fingerprint profile must be created, then the profile has to be activated on the corresponding channel.

The device schedules and displays the fingerprint according to the Fingerprint token returned by the SSM service.

A Fingerprint surface is generated for each zap based on the Content Authorization token data by target the (25.10) QuickMark (QM) Surface V3 interface.

2. Workflow diagram

3. Setup fingerprint campaigns

3.1. Create a channel

ISPM endpoint : /ispm/topologyservice/v1/channels/

Request payload example :

JSON

{
	"key": "fingerprint_channel",
	"target": "OTT",
	"contentId": "contentABC",
	"usageRulesProfileId": null,
	"sessionControlEnabled": null
}

3.2. Create a fingerprint profile

ISPM endpoint : /ispm/topologyservice/v1/fingerprintprofiles

Request payload example:

JSON

{
	"key": "fingerprint_profile",
	"textMark": {
		"message": {
			"customText": "custom text"
		},
		"agnosticTextRenderer": {
			"textDisplayAttribute": {
				"repetitionInterval": 2,
				"displayCounter": 10,
				"displayDuration": 10,
				"appendDate": true,
				"appendTime": true
			},
			"agnosticTextStyle": {
				"color": "BLACK",
				"transparency": 0,
				"backgroundColor": "BLACK",
				"backgroundTransparency": 0,
				"height": 10
			},
			"displayZonePosition": {
				"xstart": 0,
				"xend": 10,
				"ystart": 0,
				"yend": 10
			},
			"agnosticPositionInZone": {
				"xstart": "RANDOM",
				"ystart": "RANDOM"
			}
		}
	}
}

3.3. Link the fingerprint profile and the channel

ISPM endpoint : /ispm/topologyservice/v1/channels/<channel_key>/targets/OTT/fingerprintactivations

Request endpoint:

/ispm/topologyservice/v1/channels/fingerprint_channel/targets/OTT/fingerprintactivations

Request payload example:

JSON

[
	{
		"startDate": "2025-01-31T12:20:34.896Z",
		"endDate": "2025-01-31T12:25:34.896Z",
		"missingProfileBehavior": "DO_NOTHING",
		"groups": [
			"fingerprint_group_ID_1"
		],
		"profileKey": "fingerprint_profile"
	}
]

4. Fingerprint token generation

SSM endpoints :

/ssm/v1/setup
- Initializes the fingerprint messaging
/ssm/v1/heartbeat
- Renews the fingerprint token and retrieve the next campaigns

Session setup token payload example:

JSON

{
  "typ": "ContentAuthZ",
  "ver": "1.0",
  "exp": 1896359325,
  "device": {
    "watermarking": true,
    "accountId": "qmv3-100",
    "fingerprintId": "FP_ID",
    "fingerprintGroupIds": [
      "fingerprint_group_ID_1",
      "test"
    ]
  },
  "contentRights": [
    {
      "contentId": "test-content-qm",
      "sessionControl": {
        "maxSessions": 100
      }
    }
  ]
}

5. Fingerprint surface generation

QM endpoint : /qm/v3/surfaces

Token payload example:

JSON

{
  "typ": "ContentAuthZ",
  "ver": "1.0",
  "exp": 1896359325,
  "device": {
    "watermarking": true,
    "accountId": "qmv3-100",
    "fingerprintId": "FP_ID",
    "fingerprintGroupIds": [
      "test-content-qm",
      "test"
    ]
  },
  "contentRights": [
    {
      "contentId": "fingerprint_group_ID_1",
      "sessionControl": {
        "maxSessions": 100
      }
    }
  ]
}