Roku support

Smart Instream SDK is not available on Roku devices. However, it is possible and easy to deliver ads served by Smart using Roku Advertising Framework and Smart video Ad Calls.

This page guides you through the process of delivering ads on your Roku channel with video Ad Calls to Smart.

  1. Overview
  2. Roku Advertising Framework
  3. Generating your Ad Call URL
  4. Ad Call parameters list
  5. Smart Roku Sample and Smart BrightScript utils
  6. GDPR Compliance
  7. Limitations

Overview

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 Roku_Ads()
  • Generate your Ad Call URL (manually or with Smart 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&param2=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
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&vaf=0&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 supported parameters in Ad Call URLs.

Name Description Value(s) Mandatory
Placement informations
siteid Site ID of your placement Integer
pgid Page ID of your placement Integer
fmtid Format ID of your placement Integer
Keyword targeting
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
oc One call 1
out Response output format vast2
vast3
visit Ad visit type M = master
vcn No ad counting s = server side
vaf Video as flash 0
tmstp Timestamp Unix timestamp
Advertising informations (highly recommanded)
buid Bundle ID: your channel identifier. Custom String or
ROKU_ADS_APP_ID
appname Your channel name Custom String
uid User identifier or IFA. An unique identifier used for tracking and capping. Custom String or
ROKU_ADS_TRACKING_ID
User's privacy informations
gdpr_consent A base64url string representing the user's consent, conform to IAB's transparency and consent framework. String
RTB informations
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
Content Data
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
cts Season number Integer
cte Episode number 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 .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 this script in your channel's source.

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 Smart Instream SDK.

Here is a list of the features that will be missing when using RAF.

Feature Roku
Ad Rules
Ad Player Configuration
Smart Viewability Tracking
Maximum AdPod duration
Minimum time between AdBreaks
Clickthrough
Skippable ads