WebRV SDK Guide

in 3 Steps

Rewarded Video Integration for Web

Follow this guide to integrate the Rise Rewarded Video for Web to monetize your website or application!

Step 1.

Add Your Site/App to the Rise Platform

First, log in to your Rise account, then you’ll need to add your app to our platform.

 

Add Your App

1. Navigate to the ‘Apps’ settings tab in the left menu and select ‘Create App’ from the top right corner:

2. Edit the new web app with inserting the app name and the page URL:

Edit the Default Placement

I. Edit the default Rewarded Video placement of the web app you just added:

1. Reward Item Name: Your virtual currency name, in plural form (e.g. Tokens).

2. Reward Amount: Define the amount of reward items the user will receive in exchange for watching a video ad

Note:  Web applications can run exclusively on default placements.

Activate the Ad Unit

To go live with the Rewarded Video ad unit, you will need to reach out to your account manager.

Step 2.

Integrate the SDK in Your Site/App

Integrate the SDK

To integrate the Rise SDK with your site/application with our SDK, add the following code to your site:

				
					<script src="https://static.ultra-rv.com/rv-min.js"></script>
    <script type="text/javascript">
	 var ironRV = IronRV.getInstance({
		applicationKey		: "APPLICATION_KEY",
		applicationUserId	: "APPLICATION_USER_ID"
	 });
    <//script>

  • Application Key: the unique identifier for your app in Rise’s system. This parameter can be found in the Ad Units & Placements page in your Rise account:

  • Application user ID: the user ID is a unique identifier for each of your users that you need to set. We support NSString from 1 to 64 characters.

Show Rewarded Video

The JS-Tag checks the availability of campaigns for the user. If there are available campaigns – you will be notified by the “ready” event. Once ready, you can display a call to action, i.e. a button/icon/message – for example “click to earn X coins”. Once the user clicks the CTA, you must call the following function:

				
					ironRV.show();

Events

ready

Arguments: None

				
					ironRV.addListener(IronRV.EVENTS.READY, function() {
       console.log("Ready");
       });

open

Arguments: None

				
					ironRV.addListener(IronRV.EVENTS.OPEN, function() {
      console.log("Opened");
      });

closed

Arguments: None. Fired when the close button is clicked.

				
					ironRV.addListener(IronRV.EVENTS.CLOSE, function() {
      console.log("Closed");
      });

completion

Arguments: None. Fired when the user completed the offer. Use this event to gain information on the amount of rewards and award the user accordingly.

				
					ironRV.addListener(IronRV.EVENTS.COMPLETION, function() {
      console.log("Completion");
      });

no_campaigns

Arguments: None. Fired when user has completed all offers in the current session.

				
					ironRV.addListener(IronRV.EVENTS.NO_CAMPAIGNS,function() {
      console.log("No Campaigns");
      });

onAdBlockDetected

Arguments: None. Fired when system detects an AdBlock on the client.

				
					ironRV.addListener(IronRV.EVENTS.AD_BLOCK, function() {
            ironRV.showAdBlockMessage();
        });

resize

Arguments: dimensions.

				
					ironRV.addListener(IronRV.EVENTS.RESIZE, function(dimensions) {
     console.log(dimensions.width);
     console.log(dimensions.height);
     });

init_error

Arguments: None. Fired when user session is blocked by the ad server (can be variety of reasons why)

				
					ironRV.addListener(IronRV.EVENTS.INIT_ERROR, function() {
     console.log("init error");
     });

init_error

Arguments: None. Fired when user session is blocked by the ad server (can be variety of reasons why)

				
					ironRV.addListener(IronRV.EVENTS.INIT_ERROR, function() {
     console.log("init error");
     });

Full Sample Code

				
					<html>
<head>
<script src="https://static.ultra-rv.com/rv-min.js"></script>
<script type="text/javascript">
	 var params = {
		applicationKey		: "62566aa5",
		applicationUserId	: "my-user-id"
	 };
	 ironRV = IronRV.getInstance(params);
	 ironRV.addListener(IronRV.EVENTS.READY, function() {
		console.log("Ready");
	 });
	 ironRV.addListener(IronRV.EVENTS.OPEN, function() {
		console.log("Opened");
	 });

	 ironRV.addListener(IronRV.EVENTS.CLOSE, function() {
		console.log("Closed");
	 });
	 ironRV.addListener(IronRV.EVENTS.NO_CAMPAIGNS, function() {
		console.log("No Campaigns");
	 });

	 ironRV.addListener(IronRV.EVENTS.COMPLETION, function() {
		console.log("Completion");
	 });

	 function showRV() {
		ironRV.show();
	 }
  </script>
</head>
<body>
  <button onClick="showRV()">ShowRV</button>
</body>
</html>

Step 3.

Add the Callback to Your Site/App (Optional)

By default, you will receive callbacks to your client to inform you of completions and user rewards. In addition, if you wish to receive callbacks to your server, follow the below instructions to set these up.

Note:  If you're using callbacks to trigger awards to your users, make sure to not reward the user twice. You should use only one type of callback (client-side or server-side) to prompt rewards.

S2S Callback URL

Our server-to-server callback is an HTTP GET script that will be called from our servers to inform you about a commission event. The URL must include the following placeholders, which can be located anywhere in your URL, according to your preference:

Placeholder
Mandatory
Description
[USER_ID]
Mandatory
The identification of the user to be credited. Note that the URL-encoded form will be passed in this placeholder, for example, “123%40abc.com” rather than “123@abc.com”
[REWARDS]
Mandatory
The amount of points to be credited to the user.
Note: You can use this callback to your server instead of client-side completion callback to trigger rewards to your users.
[EVENT_ID]
Mandatory
A unique identifier of the commission event, represented as a MD5 string (32 alphanumeric characters)
[ITEM_NAME]
Optional
This placeholder is for publishers using the “item unlock” parameters. More details in the Advanced Settings table
Private Key
Highly Recommended
A custom string which will be used to hash each callback call and other sensitive information. You can use it in order to verify the authenticity of callback events.
Admin user id
Optional
Your personal user ID for this application/site. Offers that are presented to this particular user ID can be manipulated for testing purposes. Encode this user ID (for example, enter “123@abc.com” rather than “123%40abc.com”). More details in the callback functionality section below.

HTTP Callback Parameters

Our system will automatically add two parameters to the HTTP callback URL:

1. Timestamp – a string representation of the exact timestamp in which this callback has been called, in the following format: [4 digit year][2 digit month][2 digit day][2 digit hour][2 digit minute], e.g. “201701021455” stands for January 2, 2017 14:55.

2. Signature – an MD5 hash string based on sensitive parameters, which you can use to verify that the callback came from our system. This key is generated automatically based on the following formula:
md5([TIMESTAMP][EVENT_ID][USER_ID][REWARDS][PRIVATE_KEY]). The [USER_ID] element is the URL-decoded value of the userID (for example, “123@abc.com” rather than “123%40abc.com”).

In addition, you will receive a Private Key. The [PRIVATE_KEY] element is the exact string that you supplied when you defined your application/site. By generating the MD5 hash string using the very same parameters on your side and comparing it to the value in the signature parameter that you received from us, you can safely authenticate each callback event.

HTTP Callback Custom Parameter

In order to pass custom parameter within the callback , you will need to add another parameter during the initialization of the API called “pubCustomParams”:

  • This parameter can be used for any type of information you want pass in the callback

  • This parameter accepts type of array with pair of “key:value” separated by comma

  • The SDK supports up to three custom parameters that can be sent every time

  • The custom parameter have to be url encoded string

Sample Code:

				
					<script type="text/javascript">
	 var ironRV = IronRV.getInstance({
		applicationKey		: "APPLICATION_KEY",
		applicationUserId	: "APPLICATION_USER_ID",
		pubCustomParams      : [custom1:”value1”,custom2:”value2”]
	 });
</script>

Callback Functionality

Whenever a commission event is generated, our server will call your callback URL and provide the necessary information you need to credit the relevant user.

Our server will keep calling this URL periodically for every commission until it receives a valid HTTP response with status 200 (Ok), where the “[EVENT_ID]:OK” string appears somewhere in the HTTP response.

Here is an example of a typical response:

				
					<xml>
    <status>dae8e6cf42b1357f8652ad6ecb5b24f1:OK</status>
    </xml >

Thanks to this methodology, any temporary communication problems will not prevent crucial information from reaching its destination.

Important: If a timeout is reached (no response to the server for longer than 60 seconds), the HTTP call will be considered an error and will be followed up by an additional callback. To prevent situations of faulty extra credits resulting from timeouts, you should rely on the [EVENT_ID] parameter and ignore multiple calls made for the very same commission. As a rule, our system will never call the same commission with the same [EVENT_ID] more than once, unless a previous attempt yielded an HTTP error of any kind or if the “[EVENT_ID]:OK” string cannot be detected in the HTTP callback response.

We recommend taking additional measures to secure callbacks. You may reject any calls that do not originate from the following IP addresses:

  • 54.160.105.162

  • 52.20.168.77

CallbackRise Windows Web SDK implementation Functionality

We’ve suggested a way for implementation for WIndows web app applications, however, it is for you to decide how you want to implement & it can be used in any other way that seems right for you as the developer.

We have built the application connection to the SDK web-based & it can be found here: https://static.ultra-rv.com/ms/ms_app_sample.html

Below you can review sample projects that demonstrate the implementation of our web SDK:

1. Windows store c# application: https://static.ultra-rv.com/ms/optin_demo_csharp.zip
2. Windows store c++ application https://static.ultra-rv.com/ms/optin_demo_cpp.zip
3. Native c++ application https://static.ultra-rv.com/ms/optin_desktop_cpp.zip
Please note that after creating your own connector HTML to the app it needs to be updated in the app manifest to the new path you have created.

For Microsoft Apps integration, please add the bold line as part of the JS code, this will support presenting user-acquisition campaigns among your properties:

				
					<script type="text/javascript">
	 var ironRV = IronRV.getInstance({
applicationKey : "APPLICATION_KEY",
applicationUserId : "APPLICATION_USER_ID",
storeId: "MICROSOFT_ADVERTISER_ID"
});
</script>