Comment on page

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 the configuration is done, users start receiving the reward for viewing the video ads without needing to install anything on their device.
Requirements
You have 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 YOUR_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 an OguryOptinVideoAd instance variable in the Activity where you want to display an ad:
private OguryOptinVideoAd optinVideo;
In the onCreate method of the Activity, instantiate the Opt-in Video:
@Override protected void onCreate (Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    optinVideo = new OguryOptinVideoAd(this, "YOUR_AD_UNIT_ID");
}
OguryOptinVideoAd takes the following parameters:
a reference to any kind of Context.
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 listener to reward the user
To reward your users for watching a video, you need to register an OguryOptinVideoAdListenerlistener just after the instantiation of the OguryOptinVideoAd:
@Override protected void onCreate (Bundle savedInstanceState) {
    super.onCreate(savedInstanceState)
    // ...
    optinVideo = new OguryOptinVideoAd(this, "YOUR_AD_UNIT_ID");
    optinVideo.setListener(optinVideoListener);
}
​
private final optinVideoListener= new OguryOptinVideoAdListener() {
    @Override public void onAdRewarded(OguryReward oguryReward) {
        // reward the user here
        Log.d("Ogury", "User has received reward '" + oguryReward.getName() 
            + "' with value: " + oguryReward.getValue());
    }
    // ... other callbacks
};
The OguryReward object has two String attributes: 
name: getName()
value: getValue()
You can set their attributes in the Reward setting section of the Ogury Dashboard.
The OguryOptinVideoAdListener exposes other methods to follow the lifecycle of an Opt-in Video Ad. You can find their description in the Listener section.
Load an Opt-in Video Ad
To start loading an ad, call the load method:
optinVideo.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.
Ideally, you should implement one of the two following examples depending on your use case:
Call the load method right after the Ogury.start() method in the Activity:
public class MyActivity extends Activity {
​
    private OguryOptinVideoAd optinVideo;
    
    @Override protected void onCreate (Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        OguryConfiguration.Builder oguryConfigurationBuilder = new OguryConfiguration.Builder(this, "OGY-XXXXXXXXXXXX");
        Ogury.start(oguryConfigurationBuilder.build());
        
        optinVideo = new OguryOptinVideoAd(this, "YOUR_AD_UNIT_ID");
        optinVideo.setListener(optinVideoListener);
        optinVideo.load();
    }
    
    private final optinVideoListener= new OguryOptinVideoAdListener() {
        @Override public void onAdRewarded(OguryReward oguryReward) {
            // reward the user here
            Log.d("Ogury", "User has received reward '" + oguryReward.getName() 
                + "' with value: " + oguryReward.getValue());
        }
        // ... other callbacks
    };
​
}
Call the load method in the onCreate method of your other Activity:
@Override protected void onCreate (Bundle savedInstanceState) {
    super.onCreate(savedInstanceState)
    
    optinVideo = new OguryOptinVideoAd(this, "YOUR_AD_UNIT_ID");
    optinVideo.setListener(optinVideoListener);
    optinVideo.load();
}
​
private final optinVideoListener= new OguryOptinVideoAdListener() {
    @Override public void onAdRewarded(OguryReward oguryReward) {
        // reward the user here
        Log.d("Ogury", "User has received reward '" + oguryReward.getName() 
            + "' with value: " + oguryReward.getValue());
    }
    // ... other callbacks
};
Step 3: Show an Opt-in Video Ad
To display the ad, call the show method:
optinVideo.show();
If the method fails to show the ad, the onAdError callback is called.
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 callbacks of the OguryOptinVideoAdListener interface to follow the lifecycle of the Opt-in Video Ad. If you encounter the onAdError callback, you can check the Error codes section below to understand the error and get some advice on how to solve the issue.
Additionally, you can follow the integration logs to get useful information on your integration status and any issue that might occur when displaying ads.
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:
optinVideo.isLoaded()
If you want to be informed when the ad is ready to be displayed, you can also register a listener and override the onAdLoaded method.
Server-side reward callback
Additionally to calling the onAdRewarded callback, Ogury can notify your server when a user must be rewarded. As an 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, the 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 AAID.
#[ADVERT_ID]
Unique internal identifier associated to the impression.
#[REWARD_NAME]
Name of the reward.
#[REWARD_VALUE]
Value of the reward.
#[TIMESTAMP]
Timestamp in UNIX format.
#[APP_USER_ID]
User identifier that can be set from the SDK. 
See the Set user id section for more details.
#[VERIFIER]
Optional parameters to ensure that the call comes from the Ogury server. See Secure the server-side callback section for more details. 
Example:
https://example.com/reward?appuserid=#[APP_USER_ID]&reward_value=#[REWARD_VALUE]
Set user id
You can configure the value that will be sent to the server inside the #[APP_USER_ID] parameter for the current user by calling the following method:
optinVideo.setUserId("YOUR_USER_ID");
Secure the server-side callback
If you want to ensure that all the calls to the callback are originated from the Ogury servers, you can:
enable the 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 the Ogury servers.
The following snippet will help you to implement the computation of the verifier depending of the technology used by your server:
Bash
Node
echo -n "$ADVERT_ID:$TIMESTAMP" | openssl dgst -sha256 -hmac "$secure_key"
const verifier = crypto.createHmac('sha256', secure_key)
    .update(`${advert_id}:${timestamp}`)
    .digest('hex');
Listeners
Listen to the lifecycle of ads
The Ogury SDK provides the OguryOptinVideoAdListener interface to listen to the lifecycle of an Opt-in Video Ad instance. 
You should already have registered an OguryOptinVideoAdListener in the step 2. Otherwise, you can add the following code just after instantiating the OguryOptinVideoAd to do so:
optinVideo.setListener(new OguryOptinVideoAdListener() {
    // ...
});
The OguryOptinVideoAdListener exposes the following method in addition to the onAdRewarded method:
Methods
Definition
onAdLoaded
The SDK is ready to display the ad provided by the ad server.
onAdDisplayed
The ad has been displayed on the screen.
onAdClicked
The ad has been clicked by the user.
onAdRewarded
The user must be rewarded, as they has watched the Opt-in Video Ad.
onAdClosed
The ad has been closed by the user.
onAdError
The ad failed to load or display. The oguryError parameter contains the reason of the failure. All error codes are detailed in the section below.
Listen to the ad impressions
The Ogury SDK also provides the OguryAdImpressionListener interface to listen and count the ad impressions. 
To register an OguryAdImpressionListener, add the following code before calling the show method:
optinVideo.setAdImpressionListener(new OguryAdImpressionListener() {
    @Override public void onAdImpression() {
        // count an impression
    }
});
The OguryAdImpressionListener exposes the following method:
Methods
Definition
onAdImpression
The ad has triggered an impression.
Error codes
When an ad fails to load or to be displayed, the SDK calls the onAdError callback with an OguryError object. The OguryError object contains the cause of the failure. You can get the error code by calling the getErrorCode method and a more explicit message by calling the getMessage method.
The error codes that you can encounter are defined in the OguryAdFormatErrorCode object:
Name
Value
Definition
NO_INTERNET_CONNECTION
0
No Internet connection
The device has no Internet connection. Try again once the device is connected to the Internet.
LOAD_FAILED
2000
Load failed
The ad failed to load for an unknown reason.
AD_DISABLED
2001
Ad disabled
Ad serving has been disabled for this placement/application.
PROFIG_NOT_SYNCED
2002
Profig not sync
An internal SDK error has occurred.
AD_EXPIRED
2003
Ad expired
The loaded ad is expired. You must call the show method within 4 hours after the load.
SDK_INIT_NOT_CALLED
2004
SDK init not called
The Ogury.start() method has not been called before a call to the load or show methods.
ANOTHER_AD_ALREADY_DISPLAYED
2005
Another ad already displayed
Another ad is already displayed on the screen.
SDK_INIT_FAILED
2006
SDK init failed
An error occurred during the initialization of the SDK.
ACTIVITY_IN_BACKGROUND
2007
Activity in background
You tried to show an ad while the application was in background. Make sure to only call theshow method when the application is visible to the user.
AD_NOT_AVAILABLE
2008
Ad not available
The server returns no ads.
AD_NOT_LOADED
2009
Ad not loaded
The server returns an ad but something went wrong with the ad precaching.

Ad Formats - Previous

Interstitial Ad

Next - Ad Formats

Banner Ad

Last modified 8d ago

Name	Value	Definition
`NO_INTERNET_CONNECTION`	`0`	No Internet connection The device has no Internet connection. Try again once the device is connected to the Internet.
`LOAD_FAILED`	`2000`	Load failed The ad failed to load for an unknown reason.
`AD_DISABLED`	`2001`	Ad disabled Ad serving has been disabled for this placement/application.
`PROFIG_NOT_SYNCED`	`2002`	Profig not sync An internal SDK error has occurred.
`AD_EXPIRED`	`2003`	Ad expired The loaded ad is expired. You must call the `show` method within 4 hours after the `load`.
`SDK_INIT_NOT_CALLED`	`2004`	SDK init not called The `Ogury.start()` method has not been called before a call to the `load` or `show` methods.
`ANOTHER_AD_ALREADY_DISPLAYED`	`2005`	Another ad already displayed Another ad is already displayed on the screen.
`SDK_INIT_FAILED`	`2006`	SDK init failed An error occurred during the initialization of the SDK.
`ACTIVITY_IN_BACKGROUND`	`2007`	Activity in background You tried to `show` an ad while the application was in background. Make sure to only call the`show` method when the application is visible to the user.
`AD_NOT_AVAILABLE`	`2008`	Ad not available The server returns no ads.
`AD_NOT_LOADED`	`2009`	Ad not loaded The server returns an ad but something went wrong with the ad precaching.

Template	Definition
`#[APIKEY]`	Asset key of the application.
`#[ADUNITID]`	Ad unit ID.
`#[ADVERTISING_ID]`	User AAID.
`#[ADVERT_ID]`	Unique internal identifier associated to the impression.
`#[REWARD_NAME]`	Name of the reward.
`#[REWARD_VALUE]`	Value of the reward.
`#[TIMESTAMP]`	Timestamp in UNIX format.
`#[APP_USER_ID]`	User identifier that can be set from the SDK. See the Set user id section for more details.
`#[VERIFIER]`	Optional parameters to ensure that the call comes from the Ogury server. See Secure the server-side callback section for more details.

Methods	Definition
`onAdLoaded`	The SDK is ready to display the ad provided by the ad server.
`onAdDisplayed`	The ad has been displayed on the screen.
`onAdClicked`	The ad has been clicked by the user.
`onAdRewarded`	The user must be rewarded, as they has watched the Opt-in Video Ad.
`onAdClosed`	The ad has been closed by the user.
`onAdError`	The ad failed to load or display. The `oguryError` parameter contains the reason of the failure. All error codes are detailed in the section below.

Methods	Definition
`onAdImpression`	The ad has triggered an impression.