Roku support
Equativ Instream SDK is not available on Roku devices. However, it is possible and easy to deliver ads served by Equativ using Roku Advertising Framework and Equativ video Ad Calls.
This page guides you through the process of delivering ads on your Roku channel with video Ad Calls to Equativ.
Table of contents
- Overview
- Roku Advertising Framework
- Generating your Ad Call URL
- Ad call parameters list
- Smart Roku Sample and Smart BrightScript Utils
- GDPR Compliance
- Limitations
Overview
Equativ does not provide a dedicated library to display ads on Roku devices. However, Roku’s software is bundled with a VAST 2.0 and VAST 3.0 compliant library called Roku Advertising Framework (RAF). This library is responsible for making ad calls, parsing VAST responses into consumable video ads, rendering them and sending all relevant tracking pixels, just like Equativ Instream SDK does on other platforms.
This library has been tested by Equativ and is compliant with our video solution to display preroll, midroll and postroll ads.
The rest of this page describes you how to use Roku Advertising Framework to leverage all Equativ ad serving capabilities.
Roku Advertising Framework
You will need to setup RAF in your channel. You can follow the integration guide on Roku’s developer website. The basic setup is very simple.
This is the steps you’ll need to implement to be able to show ads with RAF:
- Initialize RAF with
Roku_Ads() - Generate your Ad Call URL (manually or with Equativ Brightscript Utils)
- Pass the Ad Call URL to RAF when needed (preroll, midroll, postroll) with
RAF.setAdUrl() - Trigger the ad call with
RAF.getAds() - Show the ads when relevant with
RAF.showAds()
Triggering preroll and postroll ads is very easy when observing your content player status. For midrolls, you will have to implement your own logic, depending on the number of ads you want to show according to the content duration. You will basically create the SVSAdRules equivalent for your channel. We will not go into details for this part since implementations vary a lot from one channel to another.
Generating your Ad Call URL
To generate your Ad Call URL you first need your baseURL. It is often a subdomain of smartadserver.com. If you do not know this baseURL, please ask your account manager about it.
Your custom Ad Call URL should start like that:
https://yoursubdomain.smartadserver.com/ac?
Note that ac? stands for Ad Call. This is the path to request your VAST response. You can add your parameters after the question mark, in any order following the usual pattern of param=value. Parameters must be separated by an ampersand resulting in ac?param1=value1¶m2=value2.
There are several sets of parameters that can be added, some are mandatory, others are not. You will find a full list of the parameters at the end of this section.
You must provide parameters about:
- Your placement
- The ad break
- Equativ mandatory video params
You can provide parameters about:
- Keyword targeting
- Advertising informations
- Your RTB requirements
- Your content data
- User’s privacy preferences
When your done generating the Ad Call URL, you should get an URL looking like this one:
https://yoursubdomain.smartadserver.com/ac?siteid=213040&pgid=901271&fmtid=29117&tgt=roku&ab=1&ps=1&pb=0&oc=1&out=vast3&visit=M&vcn=s&tmstp=1523883950&buid=ROKU_ADS_APP_ID&appname=SmartOnRoku&uid=ROKU_ADS_TRACKING_ID&vpw=1920&vph=1080&vdmin=10&vdmax=60&vbrmin=200&vbrmax=5000&vpmt=1&pgDomain=domain.com&ctid=contentID&ctn=title&ctt=type&ctc=category&ctd=60&cts=1&cte=1&ctr=rating&ctpid=providerid&ctp=providername&ctdid=distribid&ctdn=distribname&ctk=tag1,tag2&ctxid=external&ctmsid=cms&gdpr_consent=IABTCFbase64urlencodedconsentstring
Ad call parameters list
Here is the list of supported parameters in Ad Call URLs.
| Name | Description | Value(s) | Mandatory |
|---|---|---|---|
| Placement informations | |||
| siteid | Site ID of your placement | Integer | Supported |
| pgid | Page ID of your placement | Integer | Supported |
| fmtid | Format ID of your placement | Integer | Supported |
| Keyword targeting | |||
| tgt | Targeting String | Custom String | Not supported |
| Ad break informations | |||
| ab | Ad break type | 1 = preroll 2 = midroll 3 = postroll |
Supported |
| ps | Number of instances: the number of ads in the requested Adpod | Integer | Supported |
| pb | Number of passbacks | Integer | Supported |
| Mandatory Smart parameters | |||
| oc | One call | 1 | Supported |
| out | Response output format | vast2 vast3 |
Supported |
| visit | Ad visit type | M = master | Supported |
| vcn | No ad counting | s = server side | Supported |
| tmstp | Timestamp | Unix timestamp | Supported |
| Advertising informations (highly recommanded) | |||
| buid | Bundle ID: your channel identifier. | Custom String or ROKU_ADS_APP_ID |
Not supported |
| appname | Your channel name | Custom String | Not supported |
| uid | User identifier or IFA. An unique identifier used for tracking and capping. | Custom String or ROKU_ADS_TRACKING_ID |
Not supported |
| User’s privacy informations | |||
| gdpr_consent | A base64url string representing the user’s consent, conform to IAB’s transparency and consent framework. | String | Not supported |
| RTB informations | |||
| vpw | Video player width (in pixels) | Integer | Not supported |
| vph | Video player height (in pixels) | Custom String | Not supported |
| vdmin | Video duration min. Minimum duration of RTB video creatives (in seconds) | Integer | Not supported |
| vdmax | Video duration max. Maximum duration of RTB video creatives (in seconds) | Integer | Not supported |
| vbrmin | Video bitrate min. Minimum bitrate of RTB video creatives (in kbps) | Integer | Not supported |
| vbrmax | Video bitrate max. Maximum bitrate of RTB video creatives (in kbps) | Integer | Not supported |
| vpmt | Video playback method | 1 | Not supported |
| pgDomain | Your website page domain | Custom String | Not supported |
| Content Data | |||
| ctid | Content ID | Custom String | Not supported |
| ctn | Content name | Custom String | Not supported |
| ctt | Content type | Custom String | Not supported |
| ctc | Content category | Custom String | Not supported |
| ctd | Content duration (in seconds) | Integer | Not supported |
| cts | Season number | Integer | Not supported |
| cte | Episode number | Integer | Not supported |
| ctr | Content rating | Custom String | Not supported |
| ctpid | Content provider ID | Custom String | Not supported |
| ctp | Content provider name | Custom String | Not supported |
| ctdid | Content distributor ID | Custom String | Not supported |
| ctdn | Content distributor name | Custom String | Not supported |
| ctk | Content keywords. Multiple keywords describing the content, separated by commas. | Custom String | Not supported |
| ctxid | Content external ID | Custom String | Not supported |
| ctmsid | CMS identifier | Custom String | Not supported |
Smart Roku Sample and Smart BrightScript Utils
This sample illustrates the integration of video ads served by Smart on Roku devices.
You will find a SmartAdServer.brs file containing several utility functions helping you to build your direct video Ad Call URL. Once the Ad Call URL is generated, you just have to pass it to the .setAdUrl(myAdCallURL) function of your Roku Advertising Framework instance and fetch your ads with .getAds().
Here is an example on how to use the utility functions to generate your Ad Call URL. See the functions documentation in the script for a detailed description of the parameters.
' Generate ad call URL
adCallUrl = BuildAdCallURL("http://mobile.smartadserver.com", "213040", "901271", "29117", "roku", 1, 1, 0)
adCallUrl = AddAdvertisingMacrosInfosToAdCallURL(adCallUrl, "SmartOnRoku")
adCallUrl = AddRTBParametersToAdCallURL(adCallUrl, 1920, 1080, 10, 60, 200, 5000, 1, "domain.com")
adCallUrl = AddContentDataParametersToAdCallURL(adCallUrl, "contentID", "title", "type", "category", 60, 1, 1, "rating", "providerid", "providername", "distribid", "distribname", "tag1,tag2", "external", "cms")
adCallUrl = AddPrivacyParametersToAdCallURL(adCallUrl, "IABTCFBase64urlConsentString")
print "AdCallURL: "; adCallUrl
' Set Ad call URL to RAF
RAF.setAdUrl(adCallUrl)
' Ask Smart adserver for the preroll
currentAdPod = RAF.getAds()
' Ask to show the preroll ads if any
if currentAdPod <> invalid and currentAdPod.count() > 0
keepPlaying = RAF.showAds(currentAdPod, invalid, view)
end if
Note: the call to AddAdvertisingMacrosInfosToAdCallURL(), AddRTBParametersToAdCallURL(), AddContentDataParametersToAdCallURL() and AddPrivacyParametersToAdCallURL() are optional. The value returned by BuildAdCallURL() is sufficient to receive a VAST response from Smart’s delivery engine. However, we highly recommand that you also call the 4 others functions, for better monetization.
Do not hesitate to integrate our Sample script in your channel’s source.
Go to the Smart’s Sample script
GDPR Compliance
Starting 25th May 2018, the new General Data Protection Regulation law will apply in Europe. Every publisher based in Europe or offering service to users in Europe is required to comply with this regulation and collect the user’s consent to use his personal data for various purposes such as analytics or ads.
You might want to read more about how GDPR applies for advertising on advertisingconsent.eu
It is your responsability to collect the user’s consent about the use of his data and to forward it to Smart while making ad calls. For this you must pass the consent string as defined by IAB Transparency and Consent Framework specifications with the parameter gdpr_consent in the ad call URL.
The function AddPrivacyParametersToAdCallURL() in Smart BrightScript Utils can do that for you.
Limitations
Note that Roku Advertising Framework does not offer every feature available in Equativ Instream SDK.
Here is a list of the features that will be missing when using RAF.
| Feature | Roku |
|---|---|
| Ad Rules | Not supported |
| Ad Player Configuration | Not supported |
| Smart Viewability Tracking | Not supported |
| Maximum AdPod duration | Not supported |
| Minimum time between AdBreaks | Not supported |
| Clickthrough | Not supported |
| Skippable ads | Not supported |