Use audience recognition

With audience recognition, you no longer have to to preset live tags in the IXM Platform. Windows or Linux Players can now pass live tag information to an SSP provider through the AdServing API.

What are live tags?

Live tags are special tags that affect the spot playout at runtime. They’re activated and deactivated through (local) web services. This process is triggered by an attached external system that calls the player's web services. Such external systems are, for example, sensors, camera images, external dynamic data like weather forecasts, or external events. You can configure the player to display specific spots that have live tags assigned to them which match the current conditions.

System requirements

Ensure that you meet the following system requirements:

Prerequisites

Don’t forget to set the live tags that you want to pass to the SSP provider on the player. If you don’t, the add-on fetches a random spot from the AdServing API without passing the live tag information.

→ To manually set live tags on the player, you can use the API command SetLiveTags. For more information, see the API documentation.

Configure the components

To use audience recognition, you must configure the AdServing API and the player add-on.

Configure the AdServing API

For information on how to configure the AdServing API in general, see the SSP installation articles.

To configure the AdServing API, perform the following steps:

1. Open your SSP config file.

2. Specify the following settings:

   Setting	Description
   SspLiveTagsUrl	Specify the URL template of the SSP provider to allow passing live tag data. For example, if you’ve set the live tags ac1:1 and a0:5 on the player and want to send them to the SSP provider, you can use the following URL: https://prod.ssp1.eu/ssp1/?key=c762&seg=ac1%3A1%3Ba0%3A5&playerid=123 https://prod.ssp1.eu/ssp1/ is the URL of the SSP provider. key identifies the customer at the SSP server. seg stores the live tag data. playerid specifies the player’s BoxID. Note Note that if you don’t configure this setting, the application uses the value that you specified as the SspUrl instead.
   SspLiveTagValuesSeparator	Optionally, specify a separator for concatenated live tags values. By default, its a semicolon ;

3. Save your changes and close the file.

Example configuration of the SSP config file:

{
	"SspConfigurations": [
		{
			"SspPriority": 1,
			"SspUrl": "https://prod.ssp1.eu/ssp1/?key=c762&boxId={boxId}",
			"SspLiveTagsUrl": "https://prod.ssp1.eu/ssp1/?key=c762&boxId={boxId}&seg={seg}",
			"CutMediaUrlBeforeSubString": "?",
			"SspRequestHeaders": {
				"api-key": "8618681688"
			},
			"SspCategoryId": 812,
			"SspPlaylistId": 522,
			"SspSpotGroupId": 1211,
			"SspServiceUserId": 844
		}
	]
}

Configure the player add-on

To configure the player add-on, perform the following steps:

1. Open the config.ini file:

   • On Windows, the config file is located at: C:\GVClient\addonConfigs\gfPlayer\DoohPlaybackService\config.ini

   • Under Linux, the config file is located at: /opt/grassfish/addonConfigs\gfPlayer\DoohPlaybackService\config.ini

2. In the config file, specify the following setting:

   Setting	Description
   Dooh.SspLiveTagKey	If the player has live tag values with this key, all values of this live tag key are passed URL-encoded to the parameter SspLiveTagsUrl. The default value is ADV_SEGMENTS. Note You can only set one live tag key.

3. Save your changes and close the file.

Example communication to the player:

[
  {
    "Name": "ADV_SEGMENTS",
    "Values": {
      {
        "Value": "a12:2"
      },
      {
        "Value": "bx1:1"
      },
      {
        "Value": "rx1:5"
      }
    }
  }
]

Playout of SSP spots

By default, there is a look-back time of ten minutes.

For example, if you have an airtime ratio of 50%, for example, the SSP spots are played out as follows:

• If DOOH and SSP spots were played one minute in total within the last ten minutes, the system asks for a new SSP spot. One minute equals 10% which is smaller than 50% airtime ratio.

• If DOOH and SPP spots were played nine minutes in total within the last ten minutes, the system doesn’t ask for a new SSP spot. Nine minutes equal 90% which is greater than 50% air time ratio.

Troubleshooting

If you run into trouble using the audience recognition feature, consider the following information.

General errors

The following errors can occur if your setup doesn’t meet the system requirements:

• If you receive a 404 error when the add-on is making a request, your AdServing API version is too old. You must install version 1.2.0 or later.

• If the new feature doesn’t work, your player add-on version is too old. You must install version 2.7.0 or later.

• If there’s no DOOH calculation in the add-on, your player version is too old. You must install version 11.13 or later.

No concatenated strings

Only concatenated string are sent to the SSP provider as live tag information. Concatenation means joining strings end-to-end by appending one string to the end of another string. To do so, use the separator that you’ve specified as SspLiveTagValuesSeparator.

Example:

• The following concatenated string works: GET https://prod.ssp1.eu/ssp1/?seg=a12%3A2%3Bbx1%3A1%3Brx1%3A5

• The following string is not supported: GET https://prod.ssp1.eu/ssp1/?seg=a12%3A2&seg=bx1%3A1&seg=rx1%3A5

No live tags on the player

You must set the live tags on the player. If you don’t, the add-on fetches a random spot from the AdServing API without passing the live tag information.

Empty live tags value

If the live tags value is null or empty, the system ignores the parameter seg. That means, it passes null to the SSP provider.

Example: GET https://prod.ssp1.eu/ssp1/?key=c762&boxId=BOX_ID&seg=

Warning logged

The system logs a warning if the live tag value contains the same character as the configured separator. For example, if you use value=a12:1 and separator=: