Smart 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 Smart Instream SDK does on other platforms.
This library has been tested by Smart 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 Smart 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
- Generate your Ad Call URL (manually or with Smart Brightscript Utils)
- Pass the Ad Call URL to RAF when needed (preroll, midroll, postroll) with
- Trigger the ad call with
- Show the ads when relevant with
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
- Smart mandatory video params
- 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:
Ad call parameters list
Here is the list of supported supported parameters in Ad Call URLs.
|siteid||Site ID of your placement||Integer|
|pgid||Page ID of your placement||Integer|
|fmtid||Format ID of your placement||Integer|
|tgt||Targeting String||Custom String|
|Ad break informations|
|ab||Ad break type||1 = preroll
2 = midroll
3 = postroll
|ps||Number of instances: the number of ads in the requested Adpod||Integer|
|pb||Number of passbacks||Integer|
|Mandatory Smart parameters|
|out||Response output format||vast2
|visit||Ad visit type||M = master|
|vcn||No ad counting||s = server side|
|vaf||Video as flash||0|
|Advertising informations (highly recommanded)|
|buid||Bundle ID: your channel identifier.||Custom String or
|appname||Your channel name||Custom String|
|uid||User identifier or IFA. An unique identifier used for tracking and capping.||Custom String or
|User's privacy informations|
|gdpr_consent||A base64url string representing the user's consent, conform to IAB's transparency and consent framework.||String|
|vpw||Video player width (in pixels)||Integer|
|vph||Video player height (in pixels)||Custom String|
|vdmin||Video duration min. Minimum duration of RTB video creatives (in seconds)||Integer|
|vdmax||Video duration max. Maximum duration of RTB video creatives (in seconds)||Integer|
|vbrmin||Video bitrate min. Minimum bitrate of RTB video creatives (in kbps)||Integer|
|vbrmax||Video bitrate max. Maximum bitrate of RTB video creatives (in kbps)||Integer|
|vpmt||Video playback method||1|
|pgDomain||Your website page domain||Custom String|
|ctid||Content ID||Custom String|
|ctn||Content name||Custom String|
|ctt||Content type||Custom String|
|ctc||Content category||Custom String|
|ctd||Content duration (in seconds)||Integer|
|ctr||Content rating||Custom String|
|ctpid||Content provider ID||Custom String|
|ctp||Content provider name||Custom String|
|ctdid||Content distributor ID||Custom String|
|ctdn||Content distributor name||Custom String|
|ctk||Content keywords. Multiple keywords describing the content, separated by commas.||Custom String|
|ctxid||Content external ID||Custom String|
|ctmsid||CMS identifier||Custom String|
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
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
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.
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.
AddPrivacyParametersToAdCallURL() in Smart BrightScript Utils can do that for you.
Roku Advertising Framework does not offer every feature available in Smart Instream SDK.
Here is a list of the features that will be missing when using RAF.
|Ad Player Configuration|
|Smart Viewability Tracking|
|Maximum AdPod duration|
|Minimum time between AdBreaks|