-jio-start-block-type-2
-jio-style-title
VMAP is a playlist of Ads along with their timestamp at which Ad need to be played on top of the ongoing media content playback. Some HTML players can take VMAP content or URL as input and play the Ads along with the media content playback.
Complete GETTING STARTED section and INITIALIZE SDK section before starting this section.
JioAds sdk provides two approaches for supporting VMAP over media content.
1. Single Player Approach: Sharing VMAP URL to application so that the VMAP URL can be configured to content player and Ads playback is taken care by Apps player.
2. Two player Approach: If Application player don’t have VMAP playing capability then app need to inform the media time updates to SDK, seek updates to SDK and SDK will take care of detecting the ad break positions, informing app to stop content playback and starting Ad playback in different player.
-jio-style-title
Application need to provide VMAP ID created in JioAds dashboard and Queue points as inputs to SDK via tag. App need to pass content duration also as a param.
Jio Ads SDK will return VMAP URL in onVMAPReady callback if below attributes are present in INS tag as well as if onVMAPReady register by application.
-jio-style-title
Code reference
<ins
id="uid1"
data-adspot-key="nmwoh023" data-source="desktop.com" data-content-videolength="30" data-vmap-id="4ngbqw1v"
data-queue-point="5|10|15"></ins> -jio-style-title
Callback to receive VMAP Ad object
JioAds.onVMAPReady = function(placementId, options) {
console.log('CB: onVMAPReady: ', placementId, options.url);
-jio-style-title
List of VMAP Elements
-jio-tables
| data-element | values |
|---|---|
| data-content-video-length | 30 |
| data-vmap-id | 4ngbqw1v |
| data-queue-point | 5|10|15 |
-jio-style-title
JioAds sdk supports below formats of VMAP playback:
1. VMAP URL: App can pass the VMAP URL from 3rd party servers to SDK
2. VMAP content as string: If App is having vmap data as string which it got from some other means(CMS etc,.) that can be passed here
-jio-style-title
Step 1: Use the jioAds.js SDK from CDN
Use the tag inside <head> or before <body> ends.
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initialscale=1.0, maximumscale=1.0" /> <title>Web Application</title>
<link rel="stylesheet" href="css/common.css" />
<script src=" https://xxxxx/vmap/jioAds.js"></script>
</head>
<body>
// Body content goes here <div>
Hello World!
</div>
<!— OR u can put here -->
<script src=" https://xxxxx/vmap/jioAds.js"></script>
</body>
</html>-jio-style-title
Step 2:
Application need to call JioAds.setConfiguration() for providing any meta data for targeting or overriding any default config like network timeout etc,.
var conf = {
ai: "desktop.com.parent",
logLevel: 1, //debug: 1, log: 2, info: 3, trace: 4, warn: 5, error: 6
adRequestTimeout: 6000,
adRenderingTimeout: 5000,
// globalMetaData: {ct:'blr', g:'m', ag:'29'},
}
JioAds.setConfiguration(conf);
-jio-style-title
Step 3:
Jio Ads VMAP initialize API need to be called by application with appropriate VMAP related params and format as input. VMAP URL or VMAP content or VMAP id could be passed as input to JioAds.initVMAP().
In this API app need to provide one of the data either the vmapUrl/VmapIdData(that contains vmapId and cuePoints in form of JSON)/VmapContent directly After providing one the information App need to leave the other two parameters as empty string.
Application has to provide the container identifier where ad needs to be rendered, default CSS will be provided by SDK for Ad, app can override the UX according to their requirement.
In case of VmapUrl and VmapContent cidEnabled need to be passed as 1 and in case of VmapIdData cidEnabled need to be passed as 0.
The threshold value is the time before which ad should be prepared in case of Vmap. Default value is 5 sec.
var placementID = "vmapplacement1" // Application unique identifier for slot
var vmapUrl=""
vmapContent=""
vmapIdData = {"id":"mo8fike2","cuePoints":"5|120"}
var containerID = "videoContainerID" // div id in which vamp Ads need to be rendered
var contentDuration = 54603400 //Content total duration in Milliseconds
Jio Platforms Limited - JioAds Rev. No. 2. 0 Rev. Date – 25/11/2024 Page 39 of 44
var cid =
{"preRoll":"582_125252_52349_192422","midRoll":"582_125252_52348_192422",{"post
Roll":"582_125252_52349_192422"}
var cidEnabled = 1 //Enable Jio Ads tracker firing for Ads
var thresholdValue = 5 //Delta timestamp before which SDK will prepare the Ad ready
JioAds.initVmap(vmapUrl, vmapIdData, vmapContent, placementID, contentDuration, cid,
cidEnabled, thresholdValue)-jio-style-title
Step 4: Dispatch a Custom Event Named vmapTimeUpdate.
This event should be called with every Time Update of the video Player. This custom event will contain the current Time of the video Player.
Document.dispatchEvent(new CustomEvent(“vmapTimeUpdate”,{detail: {timeElapsed:
currentVideoPlayerTime}}))
-jio-style-title
Step n: Trigger the API to start the postRollAd.
This API will be called at the end of the content.
JioAds.runPostRollAd(placementId)
Ex. JioAds.runPostRollAd(”uid1”)-jio-style-title
Seek Handling:
Need to attach a seeked eventListeiner to the content Video Player. On seek event, app need to stop the media content playback and call below SDK API to inform about seek.
JioAds.seeked(currentTimeOfPlayer, placementId)
-jio-style-title
State machine to be followed:
• SDK will be internally fetch the VMAP data, parse the VMAP data, in case of parsing failure SDK will fire JioAds.onAdVmapFailedToLoad() callback.
• If network call is failed or timeout SDK will notify application via JioAds. onAdVmapFailedToLoad() callback.
• Ads can be of 3 types preroll, midroll, postroll
• SDK will check for preroll Ads and if exist then SDK starts Ads playback by default.
• SDK will fire prepareContent and startContent callback after preroll completes / if no preroll same prepareContent and startContent callback will be fired right after VMAP parsing complete. Only after receiving this callbacks Application need to start content playback.
• SDK will be listening the application’s player onTimeUpdate events for time progress, which will share the ongoing content time progress in milliseconds, based on which SDK will be comparing with timeoffset of next Ad break from vmap object.
• Whenever timeoffset matches with content time progress SDK will treat it as Ad break start, SDK will prepare the Ad and SDK will be firing callback like stopContent after returning the callback SDK will start the Ad playback.
• SDK will be providing callback prepareContent to the application, while last Ad playback will be going on, app can keep their content ready in this callback.
• After completion of Ad break, SDK will be providing resumeContent callback to Application to resume its content.
• After Media content is completed / reached EOF, app need to call runPostRollAd API.
• When Postroll is enabled SDK will render the postroll ads and after completion SDK will fire cleanupContent callback.
• If postroll is not present SDK will fire cleanupContent callback immediately.
• Application need to wait for this cleanupContent callback to cleanup and destroy the player container.
Preroll States: PrerollAd playback-> prepareContent -> startContent
Midroll States: stopContent -> Ad playback -> prepareContent -> resumeContent
Postroll States: runPostRollAd -> cleanupContent
Seek States: seeked -> Ad playback -> prepareContent -> resumeContent
-jio-style-title
a) startContent This callback will be given after showing the preRoll ad if present otherwise at the start this callback would be given.
b) stopContent This callback will be called when the ad is ready to be played. At that time app need to stop its content and SDK will be playing its ads. Based on platform the app needs to destroy its videoPlayer if more than 2 instances of player could not be there.
c) resumeContent This callback will be called when all the ads have been played and the app needs to resume is content Playback.
d) prepareContent This callback will be given before the end of last ad so that app could prepare its player for the content playback.
e) onVmapFailedToLoad This callback will be given in case the Vmap is Failed due to any of the below reasons: 1. Vmap is unable to be parsed 2. Vmap Url is empty. 3. Vmap Id is not associated to any URL. 4. If any of the mandatory data is absent like cid in case of url/content.
f) onVastFailedToLoad This callback will be given in case the ad Vast is Failed due to any of the below reasons: 1. Vast is unable to be parsed 2. Vast is empty.
g) cleanUpContent This callback will be given after showing the postroll ad if / not present.
-jio-end-block-type-2