Using Thirdpresence to serve video ads

From ThirdPresence Wiki

This document explains how Thirdpresence can be used to serve video ads in different use cases (in-app, mobile web etc.) to 7000+ different mobile devices.

Since Thirdpresence is not a campaign management or ad serving platform, the first thing to consider is the integration between the ad server and Thirdpresence.


Contents

Prerequisites

To complete this integration walkthrough, you will need:

Mandatory steps

  1. Upload the ad video file to Thirdpresence
  2. Insert ad data; e.g. tracking codes/clickthrough URL/etc
  3. Publish the video ad inside your ad unit

Uploading video file

To upload your video file you can either do a manual upload using the Thirdpresence Console or you can use an API call. You can find detailed documentation for the API call here: http://wiki.thirdpresence.com/index.php/10-09-API-insertVideo

When the upload is completed you will receive an id for the video, which you will need for the next step.

Inserting ad data

When inserting ad data you can define:

  • videoid - Video id (iid) which you received when uploading the video in the previous step
  • adid - Unique identifier for your ad. This is a mandatory field.
  • description - Description for your ad. This is optional.
  • advertiser - Advertiser name for this ad. This is optional.
  • impressionurls - Impression URL. See VAST specification.
  • trackingevents - Object containing event => URL-list pairs. See VAST spec.
  • videoclicks - Object containing VideoClicks element => URL-list pairs. See VAST spec.

The ad data is inserted using an API call: http://wiki.thirdpresence.com/index.php/03-13-API-insertLinearVASTAd

Now you are ready to test your video ad in different ad placements.

In-stream video advertising

In-stream video ads can be incorporated in different ways to the video playback experience. The most common way is to show an ad clip before the actual clip starts playing (video pre-roll).

You can get VAST file from following url http://[your_account_name].thirdpresence.com/dls/t/vast.jsp?adid=[adid]

Video player behavior with in-stream VAST ads 

Player     Ad server     Thirdpresence
Get VAST Ad
------------->
Redirect to VAST file
<-------------
 
Get VAST file
------------------------------->
VAST File
<-------------------------------

Get video
------------------------------->
<-------------------------------

Send tracking events
------------>
------------------------------->

HTML/MRAID ad unit embed

You can embed the video into an HTML/MRAID based ad unit as follows: 

  <div id="tpmovie"></div>
  <script src="http://[your_account_name].thirdpresence.com/dls/t/thirdpresence.js?adid=[adid]&h=360&w=640&tagid=tpmovie" type="text/javascript"></script>

You can use the following parameters to customize player behavior:

  • h - height as pixels
  • w - widht as pixels
  • tagid - define tagid where player will be inserted. Default is "tpmovie"
  • autoplay - 0|1 if defined as 1 then video will autoplay (if the device allows it)

Example: http://www.thirdpresence.com/demos/vast/index.html

In-app Video Ads

Video ad formats can be easily deployed inside mobile applications.

The simplest way to achieve this is to integrate the Thirdpresence In-App Video Player SDK into your own app SDKs.

There are many different ways to implement an in-app advertising SDK so the integration steps outlined below are just examples. Our technical team has implemented a number of different integrations into different platforms so they can probably help you if necessary.

Thirdpresence provides a native VAST 2.0 compliant video player SDK that can be used inside any app to play video ads from any VAST compliant ad server.

Note that if your ad server doesn't support VAST, the video player also supports non-VAST use-cases, however your server needs to provide the appropriate tracking methods.

The video player SDK uses caching of the video to ensure smooth playback under any network conditions.

The general workflow for playing a video ad inside an app is:

  1. The desired video ads are precached on the device when the app is launched
  2. When the app is ready to show an ad, it can ask if the video ad is ready (cached) for viewing
  3. If the video ad is ready for viewing, the app asks the video player to play the ad
  4. The video player calls the pre-set tracking and impression URLs while the ad is played

Android In-App Ad SDK

Thirdpresence's Android In-App Ad SDK supports Android 2.3.3 (API version 10) and above.

This guide explains how to install the SDK and how to integrate it with your ad server.

Setup

Here are the steps for adding the Thirdpresence In-App Ad SDK to your Android project:

  1. Download the SDK
  2. Add the VideoAdActivity.jar file to your external libraries folder
  3. Add the VideoAdActivity.jar file to your classpath

Integration

1. Add following activity to AndroidManifest.xml 

<activity android:name=".VideoAdActivity"
          android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
          android:configChanges="orientation">
</activity>

2. Set permissions for the video player SDK

The video player SDK requires the following permissions INTERNET, ACCESS_NETWORK_STATE, WRITE_EXTERNAL_STORAGE, and ACCESS_WIFI_STATE.

You can copy the following lines to your AndroidManifest.xml 

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

3. When launching the app, initialize the player SDK 

Thirdpresence thirdpresence = new Thirdpresence(
						Context context, 
						String account, 
						boolean useCache, 
						String cacheDir, 
						boolean clearCache, 
						boolean hq,
                                                Class activityClass);

context is your application android.content.Context
account is your Thirdpresence account name.
useCache defines that will videos prefetched to localcache. (It will be done only if SD Card is accessible).
cacheDir the folder on the SD card which will be used. If null then /tpvideo will be used.
clearCache if true then the cache folder will be cleared when started.
hq defines that HD video quality will be used. This option can be set when the device is on a WiFi network and there is enough local storage on the device. activityClass is class of your Video Ad Activity.

4. Pre-cache the video ads 

String[] videoIds = new String[2];
    	videoIds[0] = "807290";
    	videoIds[1] = "755450";
    	thirdpresence.cacheVideos(videoIds, null);

You can define two different arrays of video ids.

The first array uses video ids (videoid) that have been assigned by Thirdpresence to the video files that you have uploaded into your account.

The second array uses video ids (providerid) that you have specified for the video files when uploading them to your account. For more information on using providerid please see the platform API documentation.

5.1 Play a video ad using VAST (first check that the video has been cached) 

boolean cached = thirdpresence.isCached("807290", null);
Log.d(this.getLocalClassName(), "t = " + t);	
if(cached) {
	thirdpresence.showVastAd("http://str.thirdpresence.com/inapp/vast.xml");
}

isCached method takes two parameters, videoid and providerid. Only one should be defined. method returns true if video with defined id is cached.

showVastAd method plays ad which is defined at VAST. Method does not return.

To receive information about player status you should implement following methods at your Video Ad Activity 

@Override // called when video has any error
public void onVideoAdError(Exception ex) {
     Log.d(this.getLocalClassName(), "onVideoAdError");	
}
@Override // called when video is finished
public void onVideoAdFinished() {
     Log.d(this.getLocalClassName(), "onVideoAdFinished");	
}
@Override // called when video is successfully cached. Video id is given as parameter
public void onVideoAdCached(String id) {
     Log.d(this.getLocalClassName(), "onVideoAdCached");	
}


In this example, http://str.thirdpresence.com/inapp/vast.xml is the URL of the VAST server.

5.2 Play a video ad without using VAST

For more information on this method, please contact support@thirdpresence.com

iOS In-App Ad SDK

Thirdpresence iOS In-App Ad SDK supports iOS 4.2 and above (iOS 6.x).

This guide explains how to install the SDK into your application and integrate it to your ad server.

Adding the SDK into Your XCode Project

  1. Extract the package and add the library folder to your project. The folder contains the library file and the header file (ThirdpresenceInAppAdPlayer.h).
  2. Go to "Build phases" in your project's target settings, then go to "Link Binary With Libraries". Ensure that the following frameworks are added: 
    QuartzCore.framework
    AVFoundation.framework
    AudioToolbox.framework
    MobileCoreServices.framework
    SystemConfiguration.framework
    CFNetwork.framework
    MediaPlayer.framework
    CoreGraphics.framework
    libsqlite3.dylib
    libz.dylib
    libthirdpresence-ios-inapp-ad-sdk-1_0.a

Using the SDK in Your Application

1. Instantiate the ThirdpresenceInAppAdPlayer 

    ThirdpresenceInAppAdPlayer *thirdpresenceInAppPlayer =
            [[ThirdpresenceInAppAdPlayer alloc] initWithViewController:my-view-controller
                accountName:@"my-thirdpresence-account" useCache:YES clearCache:YES useHQ:NO];

initWithViewController is a pointer to the ViewController you want to use for showing the player.
accountName is your Thirdpresence account name.
useCache is a boolean value defining whether to cache the played advertisements to the local file storage.
clearCache is a boolean value defining whether to empty the cache when the SDK is initialized.
useHQ is a boolean value defining whether to use HD video quality. This option can be set when the device is on a WiFi network and there is enough local storage on the device.

2. Pre-cache the video ads

In case you have instantiated the SDK with useCache being true, you can pre-cache the videos before showing them in player. 

    NSArray *videoIds = [NSArray arrayWithObjects:@"807290", @"755450", nil];
    [thirdpresenceInAppPlayer cacheVideos:videoIds cacheVideosByRefIds:nil];

You can define what videos will be cached by giving either video IDs of the videos you have uploaded into your account, or by giving provider IDs that you specified for the uploaded videos. For more information on using providerid please see the platform API documentation.

3.1 Play a video ad using VAST

The following example checks first whether the video has been cached. If the video has not been cached yet, the showVASTAd method will play the requested video by streaming it from the source directly. 

    BOOL isCached = [thirdpresenceInAppPlayer isVideoCached:@"807290"];
    // BOOL isCached = [thirdpresenceInAppPlayer isVideoCachedByRefId:@"my-video-reference-id"];
    if (isCached) {
        [thirdpresenceInAppPlayer showVastAd(@"http://str.thirdpresence.com/inapp/vast.xml");
    }

In this example, http://str.thirdpresence.com/inapp/vast.xml is the URL of the VAST server. Notice that the VAST file in this example contains a MediaFile matching the video ID 807290.

3.2 Play a video ad without using VAST

For more information on this method, please contact support@thirdpresence.com

Retrieved from "http://wiki.thirdpresence.com/index.php/Advertising_Main"
This page was last modified on 2 May 2013, at 13:16.