Opt-in Video Ad

This article will go through all the steps required to display an Opt-in Video Ads in your application.

Opt-in Video Ads are skippable fullscreen videos. They allow you to reward users with in-app items for watching video ads.

Opt-in Video Ads can only be served to users who explicitly and previously chose to view a rewarded ad. You can specify the reward values associated with the Ad units in your application and set different rewards for different Ad units.

Once configuration is done, users start receiving the reward for viewing the video ads without needing to install anything on their device.

Requirements‌

You have a registered an application on your Ogury Dashboard. If not, please refer to the Getting Started section before the next steps.

Step 1: Create an Opt-in Video Ad ad unit

• Create an Opt-in Video Ad ad unit.
• Copy the Ad unit id as you will need this information later to finish the integration.

In all the following code samples, we will refer to this Ad unit id by using the string AD_UNIT_ID.

Step 2: Load an Opt-in Video Ad

The Ogury SDK provides the OguryOptinVideoAd object that lets you load, display and control your Opt-in Video Ads.

Instantiate an Opt-in Video Ad

• Declare a OguryOptinVideoAd instance variable in the ViewController where you want to display an ad:

Swift

var optinVideoAd: OguryOptinVideoAd?

Objective-C

@property (nonatomic, strong) OguryOptinVideoAd *optinVideoAd;

• In the viewDidLoad method of theViewController instantiate the Opt-in Video:

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    
    optinVideoAd = OguryOptinVideoAd(adUnitID: "AD_UNIT_ID")
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.optinVideoAd = [[OguryOptinVideoAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
}

OguryOptinVideoAd takes the following parameter:

• an adUnitID: the Ad unit id of the Opt-in Video Ad. If you do not have one yet, you can refer to the first step to create it.

Register a callback to reward the user

To reward your users when they watched the video, you need to register a callback just after the instantiation of theOguryOptinVideoAd:

Swift

import OgurySdk
import OguryAds
import OguryChoiceManager

class ViewController: UIViewController {

    var optInVideoAd: OguryAdsOptinVideo?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        optinVideoAd = OguryOptinVideoAd(adUnitID: "AD_UNIT_ID")
        optinVideoAd?.delegate = self
    }
}

extension ViewController: OguryOptinVideoAdDelegate {
    
    func didRewardOguryOptinVideoAd(with item: OGARewardItem, for optinVideo: OguryOptinVideoAd) {
        // Reward the user here
    }
    
    //... Other delegates
}

Objective-C

#import "ViewController.h"
#import <OgurySdk/Ogury.h>
#import <OguryAds/OguryAds.h>
#import <OguryChoiceManager/OguryChoiceManager.h>

@interface ViewController () <OguryOptinVideoAdDelegate>

@property (nonatomic, strong) OguryOptinVideoAd *optinVideoAd;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.optinVideoAd = [[OguryOptinVideoAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
    self.optinVideoAd.delegate = self;
}

- (void)didRewardOguryOptinVideoAdWithItem:(OGARewardItem *)item forAd:(OguryOptinVideoAd *)optinVideo {
    // Reward the user here
}

//... Others methods

@end

The OGARewardItem object has two String attributes:

• name: rewardName

• value: rewardValue

You can set their values in Reward setting section

The OguryOptinVideoAdDelegate exposes other methods to follow the lifecycle of an Opt-in Video Ad. You can find their description in the Delegate section.

Load an Opt-in Video Ad

To start loading an ad, call the load method:

Swift

optinVideoAd?.load()

Objective-C

[self.optinVideoAd load];

Since it may take a few seconds to fetch the ad resources (video, image, ...) from the network, you should call the load method as soon as possible after getting the user's consent.

Ideally, you should implement one of the two following examples depending on your use case:

• Call the load method right after the ask method in the ViewController that collects the consent:

Swift

import UIKit
import OgurySdk
import OguryAds
import OguryChoiceManager

class ViewController: UIViewController {

    var optinVideoAd: OguryOptinVideoAd?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let configuration = OguryConfigurationBuilder(assetKey: "OGY-XXXXXXXXXXXX").build()
        Ogury.start(with: configuration)
        
        optInVideoAd = OguryOptinVideoAd(adUnitID: "AD_UNIT_ID")
        optinVideoAd?.load()
    }
}

Objective-C

#import "ViewController.h"
#import <OgurySdk/Ogury.h>
#import <OguryAds/OguryAds.h>
#import <OguryChoiceManager/OguryChoiceManager.h>

@interface ViewController ()

@property (nonatomic, strong) OguryOptinVideoAd *optinVideoAd;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    OguryConfigurationBuilder *configurationBuilder = [[OguryConfigurationBuilder alloc] initWithAssetKey:@"OGY-XXXXXXXXXXXX"];
    [Ogury startWithConfiguration:[configurationBuilder build]];
    
    self.optInVideo = [[OguryOptinVideoAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
    [self.optinVideoAd load];   
}

@end

• Call the load method in the viewDidLoad method of your other ViewController:

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    
    optinVideoAd = OguryOptinVideoAd(adUnitID: "AD_UNIT_ID")
    optinVideoAd?.load()
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];
    
    self.optinVideoAd = [[OguryOptinVideoAd alloc] initWithAdUnitId:@"AD_UNIT_ID"];
    [self.optinVideoAd load];
}

Step 3: Show an Opt-in Video Ad

To display the ad, call the show method:

Swift

optinVideoAd?.show(in: self)

Objective-C

[self.optinVideoAd showAdInViewController:self];

The show method takes the following parameter:

• a reference to the ViewController where you will show the Opt-in Video Ad.

If the method fails to show the ad, the following delegate is called:

Swift

didFailOguryOptinVideoAdWithError(_ error: OguryError, for optinVideo: OguryOptinVideoAd)

Objective-C

didFailOguryOptinVideoAdWithError:(OguryError *)error forAd:(OguryOptinVideoAd *)optinVideo

The parameters of this callback are the following:

• error: the error which occurred while trying to display the ad. Error codes are explained below.

• optinVideo: the Opt-in Video Ad for which the error occurred.

Step 4: Test your integration

Ogury exclusively serves ads to users who have given consent. It is essential to have responded to a valid TCFv2 consent form before conducting any tests.

As our algorithm works with personified targeting, you may not receive any ad while testing your application.

You can test your integration by adding the suffix _test to your interstitial ad unit id, for more details go to Test your implementation page.

Note that if you have just registered your application in the Ogury Dashboard, it will take around 15 minutes until you can successfully load an ad.

If you are not able to display any Opt-in Video Ad, we recommend you to log every delegate on yourOguryOptinVideoAdDelegate to follow the lifecycle of the Opt-in Video ad.

If you encounter the didFailOguryOptInVideoAdWithErrorcallback , you can check the error codes section below to understand the error and get some advice on how to solve the issue.

Advanced topics

Check if an ad is ready to be displayed

Call the following method to check if an Opt-in Video Ad is ready to be displayed:

Swift

optinVideoAd?.isLoaded()

Objective-C

self.optinVideoAd.isLoaded;

If you want to be informed when the ad is ready to be displayed, you can also register a delegate and implement the didLoadOguryOptinVideoAd method.

Server-side reward callback

Additionally to calling the didRewardOguryOptinVideoAdWithItem callback, Ogury can notify your server when a user must be rewarded. As example it can be used to secure your rewarding logic if the user receives a reward equivalent to your in-app purchase currency.

In this case, Ogury servers send an HTTP GET request to a callback URL when the user has to be rewarded. The next section goes through the configuration of the callback URL in the Ogury Dashboard.

Configure the callback

To configure the callback in the Ogury Dashboard:

• Go to your Asset list and select your Asset in the list.

• Click on the Monetization settings line in the left-menu.

• Select your Ad unit to edit it.

• Click on the toggle on the right of the Callback settings to enable the server-side callback.

• Put the URL that must be called in the CALLBACK URL field.

In the URL, you can place one or more of the following templates. They will be replaced by their corresponding value by the Ogury server.

Template	Definition
#[APIKEY]	Asset key of the application.
#[ADUNITID]	Ad unit ID.
#[ADVERTISING_ID]	User IDFA.
#[ADVERT_ID]	Uniq internal identifier associated to the impression.
#[REWARD_NAME]	Name of the reward.
#[REWARD_VALUE]	Value of the reward.
#[TIMESTAMP]	Timestamp in UNIX format.
#[VERIFIER]	Optional parameters to ensure the call comes from the Ogury server. See Secure the server-side callback section for more details.

Example:

https://example.com/reward?advertising_id=#[ADVERTISING_ID]&reward_value=#[REWARD_VALUE]

Secure the server-side callback

If you want to ensure that all the calls to the callback are originated from Ogury servers, you can:

• enable SECURE CALLBACK option in the Callback settings of your Ad unit.

• include the #[TIMESTAMP], #[ADVERT_ID] and #[VERIFIER] templates in your CALLBACK URL.

Once the SECURE CALLBACK option is enabled, the Dashboard will show your secure key. The value of the #[VERIFIER] template will be computed using HMAC SHA-256 with the following parameters:

• secret key: the secure key associated to your Ad unit.

• message: concatenation of the #[ADVERT_ID] and the #[TIMESTAMP] templates.

By computing this value on your side, you will be able to verify that both server shares the same secure key and therefore that the calls come from Ogury servers.

The following snippet will help you to implement the computation of the verifier depending of the technology used by your server:

Bash

echo -n "$ADVERT_ID:$TIMESTAMP" | openssl dgst -sha256 -hmac "$secure_key"

Delegate

The Ogury SDK provides the OguryOptinVideoAdDelegate to listen to the lifecycle of an Opt-in Video Ad instance.

You should already have registered a OguryOptinVideoAdDelegate, in the step 2. Otherwise, you can add the following code just after instantiating the OguryOptinVideoAd to do so:

Swift

optinVideoAd?.delegate = self

Objective-C

self.optinVideoAd?.delegate = self;

The OguryOptinVideoAdDelegate exposes the following methods in addition to the didRewardOguryOptinVideoAdWithItem:forAd :

Methods	Definition
didLoadOguryOptinVideoAd	The SDK is ready to display the ad provided by the ad server.
didDisplayOguryOptinVideoAd	The ad has been displayed on the screen.
didClickOguryOptinVideoAd	The as has been clicked by the user.
didCloseOguryOptinVideoAd	The ad has been closed by the user.
didFailOguryOptinVideoAdWithError	The ad failed to load or display. The error parameter contains the reason of the failure. All error codes are detailed in the section below.
didTriggerImpressionOguryOptinVideoAd	The ad has triggered an impression.

Error codes

When an ad fails to load or to be displayed, the SDK will call the didFailOguryOptinVideoAdWithError callback with one of error code defined in OguryAdsError:

Name	Value	Definition
OguryCoreErrorTypeNoInternetConnection	0	No Internet connection The device has no Internet connection. Try again once the device is connected to the Internet.
OguryAdsAdDisabledError	2001	Ad disabled Ad serving has been disabled for this placement/application.
OguryAdsProfigNotSyncedError	2002	Profig not synchronized An internal SDK error has occurred.
OguryAdsAdExpiredError	2003	Ad expired The loaded ad is expired. You must call the show method within 4 hours after the load.
OguryAdsSdkInitNotCalledError	2004	SDK init not called The Ogury.start() method has not been called before a call to the load or show methods.
OguryAdsAnotherAdAlreadyDisplayedError	2005	Another ad already displayed Another ad is already displayed on the screen.
OguryAdsAssetKeyNotValidError	2006	SDK init failed An error occurred during the initialization of the SDK.
OguryAdsNotAvailableError	2008	Ad not available The server returns no ads.
OguryAdsCantShowAdsInPresentingViewControllerError	2010	A view controller is already being presented Only one view controller may be presented at a time.
OguryAdsUnknownError	2011	Unknown error An unknown error occurred.