In Synamedia Iris, content targeting is a way of specifying that an advertisement should be shown (or not shown) within the content, programme or show that a viewer is watching. It can be used alongside other targeting options (such as audience segment or device) to refine the context in which a viewer sees creatives from Line Items. It is sometimes referred to as contextual targeting.
To make the content being viewed a factor in the decision process, Synamedia Iris needs to be provided with some data about the programme. There are two main ways that this data can be supplied.
Note: The content targeting methods described below apply to the OTT Linear and OTT VOD Streaming Types. This type of granular contextual targeting is not possible for the Broadcast streaming type where you may wish to target channel lineups as a proxy for the content.
When asking Synamedia Iris for an ad decision, it is possible to add information about the programme by appending Key-Value pairs (KVP) to the VAST request. For example, a request for advertisements around a comedy show could contain KVP like ‘kvp=genre~comedy’ and Line Items could be targeted exclusively to be shown when ‘genre=comedy’ is matched in the request. In this way, advertisements may be targeted to comedy shows. When a call is being made to Synamedia Iris, you must ensure that it contains the KVPs in the proper format and that KVPs are created, as described in the Key-Value Pair Targeting documentation. You can use many KVPs in the request to describe the content, for example, ratings, year of production, sub-genres, or any other parameter that you need to describe the programme or show in a way that may be useful to your sales team and their advertisers.
Using this method, the requesting client must have access to all the information about a piece of content. If you are using a large amount of data to describe content, then having the client pass all this data may not be the most useful method to send the information to Synamedia Iris. A more efficient way of supplying larger quantities of data about programming is to use the content metadata ingest process.
The content metadata ingest process allows you to easily provide a bulk upload of your content data that Synamedia Iris can use during the decision process. After the content data has been ingested, Synamedia Iris will retain this information in a content catalogue that can be accessed for each ad request that is made. The system also uses the KVP targeting system within Iris Ad Manager, but you do not have to supply all the KVPs on each request. You should note that the requesting client must be able to pass a single content identifier on every request which Synamedia Iris uses to find KVPs associated to the content in the catalogue which will, in turn, be used in the decision process.
The content metadata supplied to Synamedia Iris describes the content (for example, the content’s genre). But using the ingest process also allows you to provide additional data that tells Synamedia Iris if there are special delivery rules that should be applied to the content. These rules are called control policies, and the system will be expanded to include a range of control policies over the coming months (see below).
The requesting client must pass along a content identifier on the decision request in the format contentID=1234. The value should be unique for each piece of content being watched so that the correct reference in the content catalogue can be found. The precise way that this is signaled will be different depending on the streaming type (for example, using SCTE markers in OTT linear) and you should contact Synamedia if you need assistance for your specific setup.
The content metadata can be supplied, in bulk, as files to an S3 location provided to you by Synamedia. The file should contain the data used to describe your programming. See Content Inventory API for information on the correct file format for the descriptive and control policy data. Each file may contain data for up to 1000 unique contentIDs. If you have more IDs, split the data into smaller files for ingest as each file will stop being processed once 1000 contentIDs have been identified. The S3 location where files must be uploaded also contains error information in a ‘failed’ directory and it is advisable to check this folder to be alerted to any errors encountered during the ingest. A maximum of 250000 contentIDs per customer can be ingested in the system.
Once processed, the file is archived in a ‘processed’ folder. It should not be assumed that, if a file is in the ‘processed’ folder, no errors have occurred. If an error is encountered, then an entry will be written to the error log and the processing will continue for other records in the file. The data that you provide to the Synamedia catalogue should contain the following pieces of information for each piece of content:
Name | Description |
|---|---|
contentId | A unique identifier for the content. |
contentType | The type of content - either LINEAR, VOD or both. |
expirationDate | The expiry date and time for the content metadata, after which it will be removed from the system. |
control | Control policies to apply to the content (see below). |
metadata | The key-value pairs that describe this content. |
The metadata provided as part of the content ingest process describes the content and should be supplied in the KVP format where each piece of content may have many keys and values associated to it. For example, genre, ratings, year of production, sub-genres, or the associated talent could be passed for each programme in your catalogue. Each key should only appear once for each contentID but it may have multiple values assigned to it (for example, a comedy drama may have the genre values comedy and drama associated with it).
Although you may have a large amount of metadata associated with content in your back office systems, Synamedia advises only providing the data that will be used in advertising targeting and ensuring the data is clear and unambiguous as it will need to be selected, as provided, by your ad operations team when creating Line Items (for example, having genre values sport and sports in your system may be confusing to system operators).
To use KVP metadata for targeting, the keys and values seen in the uploaded files must be created using the process described in the Key-Value Pair Targeting documentation. Keys and values that are not pre-configured in Synamedia Iris will be ingested into the catalogue, but they will not be targetable in the Campaign and Line Item workflow until they have been created. The maximum number of active keys that can be configured in Synamedia Iris is 200. It is possible to remove inactive keys from the system, but they cannot be deleted if they are in use in ‘in-flight’ or ‘pending’ campaigns.
The maximum length for each key name is 20 characters and 40 characters for any value. If you are, for example, providing programme name as part of the metadata (using, for example, ProgName as the key), ensure that the 40-character limit causes no ambiguity in the naming so that your ad operations team are clear on the programmes being selected. Synamedia will not truncate values in excess of 40 characters; these values will be rejected.
When all the data has been provided and processed by the system then the metadata can be added to any Line Item using the KVP targeting feature using the Campaign API or the Synamedia user interface. When a request is made to Synamedia Iris, the system will take the contentID supplied and look for the reference in the catalogue. If the ID exists, then all the KVPs associated to the content in the catalogue are evaluated as part of the targeting for that decision request alongside all the other data known for the request, including KVPs passed on the call to Synamedia Iris.
KVPs can be used for positive targeting (such as targeting all programmes that match genre=sport or exclusion targeting to prevent a Line Item being shown against genre=news).
The control policies provided as part of the content ingest process describe a special set of behaviors that Synamedia Iris should enforce for each piece of content. The number and type of control policies will be expanded in the future. The currently supported control policy is:
allowAdInsertion: A control policy identifying whether ads are enabled for this content or not. The default behavior is 'true' meaning that Synamedia Iris assumes that ads are allowed even if this setting is not present. If you do not wish advertisements to be shown for any specific IDs, then this setting should have the value ‘false’ in the catalogue for contentIDs where advertisements should not be returned. Where set to 'false', Synamedia will return a ‘no advertisement’ VAST response even if there are matching Line Items available for service.
Where a decision request that contains a content identifier that cannot be found in the catalogue is made to Synamedia Iris, then the ADS will use your system settings to determine how to respond.
By default, when a content identifier cannot be found in the catalogue, the ADS will use other available data (such as audience segment or device ID) to make a decision and an advertisement may still be returned if a suitable Line Item can be found.
It is possible to configure the ADS so that when an ID cannot be found in the catalogue, the system should respond with no advertisement. This can be useful when it is important that the content policies are enforced and, if the system is unable to find the metadata, it is better to respond with no ad. Please contact Synamedia if you would like this behavior enabled on your system.
A new file should be supplied when you wish to update the data for one or more contentIDs. You only need to supply the data for updated or new contentIDs; the whole catalogue does not need to be uploaded again. The contents of the new file will entirely replace the data for matching contentIDs that already exist in the system, partial updates for an individual record are not supported.
Content metadata, both descriptive and control policies, can be deleted by providing a file to the ‘delete’ folder in the S3 location. The format for the delete file is described in the Content Inventory API. Additionally, metadata will expire on the date included in the expiration date field. Once deleted or expired, Synamedia Iris will be unable to identify the deleted or expired contentID in the catalogue and will continue with the decision process as an unmatched ID.
Synamedia recommends taking care to set the appropriate expiry dates for content metadata, especially if control policies are used where the absence of policy information may cause unintended behaviors.
A REST API is available that allows browsing of the ingested content data so that you can confirm the data Synamedia Iris holds for your content. It is not possible to modify the data with this API. For more information, see Content Inventory API.
I am using the metadata ingest process for my programme data. Can I still pass key-value pairs on the request?
Yes, the two features can work together to pass data into the decision. The data from the request and the metadata lookup will be combined where both KVPs and a contentID exist on the call. Values passed for keys that are provided by both methods do not overwrite each other. Thus, if you pass data for genre=movie using one method and genre=sport using the other method then, for that request, both values may be used by the decision engine.
We have scheduled some last-minute content on to our service. How long does it take the metadata to be available to the decision service?
Synamedia is monitoring the directory continually and will process new data as it is added to the S3 location. Once processed, and the file is in the ‘processed’ folder, the data is immediately available to the decision service. Please check the error logs to confirm there were no errors.
How long does a data update take to be available to the decision service?
An update file is processed in the same way as new data, but data that has been used in decision requests is cached by the system for 15 minutes. Thus, an update may not be seen to have taken effect until the file has been processed and the cache has expired. It is likely that a viewer, watching a single piece of content, may make multiple ad requests and the cache aids Synamedia in managing the load across the system. If the 15-minute cache is a concern for your service, please contact Synamedia Iris to discuss adjusting the cache duration. If the update file is in the ‘processed’ folder, please check the error logs to confirm there were no errors encountered.
I have set the allowAdInsertion to false, but I am still seeing advertisements in my show. Why?
If you are still seeing advertisements when allowAdInsertion is set to false for a particular programme, verify that the contentID is both being passed and matches the record in the catalogue for the streaming type. If the information has been recently updated, please wait 15 minutes to allow the cache to update and confirm that the record for the contentID has not expired. You can verify the data of any record in the catalogue using the browsing API (see Content Inventory API for more information).
I don’t have content-specific metadata, but I would like to provide some general information about the channel. How can I do that?
The contentID system is very flexible. If a contentID is passed on the request to Synamedia Iris then the system will look-up associated metadata. In this way if, for example, you only have channel data then you could use the contentID parameter to pass a channel identifier value that would allow Synamedia Iris to retrieve the KVPs associated with that channel.
