Using the AppsPrize SDK

With the SDK initialized, this is how you open the offerwall, read what a user has earned, and pay them out. Pick your platform below.

Using the SDK

Once you have set up and initialized the SDK you can use its features:

Playtime Access

The Playtime feed comprises apps that users can install and utilize to earn rewards. This feed is presented in a distinct activity. Rather than directly initiating the activity, we furnish you with an getActivityIntent calling from AppsPrize object to start it. This approach enables you to display transition animations and implement other customizations for your users' experience.

In order to launch SDK, you can use launchActivity function as below:

Kotlin

object AppsPrize

This is a AppsPrize singleton instance to perform actions. Occurs about AppsPrize.

This will launch the launchActivity displaying the AppsPrize ad feed:

Kotlin

@JvmStatic
fun launchActivity(activity: Activity): Boolean

This function allows you to launch AppsPrizeActivity to show available campaigns and track apps' reward progress. If AppsPrize is not initialized, it returns false.

Return

Activity launch action status

Parameters

activity: Current activity

options: Offerwall Options

For the launch options;

You can set the type to be opened in offerwall, Only Time Based or Task Based. So you will be able to show specific offerwall type for different placements as well.

Kotlin

val options = AppsPrizeOfferwallOptions.Builder()
    .setType(/** AppsPrizeOfferwallType: ONLY_TIME |  ONLY_TASK | ALL */)
    .build()
AppsPrize.launch(activity, options)

This function allows you to open directly detail page given campaign ID. If AppsPrize not initialized returns false.

Kotlin

fun open(activity: Activity, campaignId: Int): Boolean

Parameters

activity: Current activity

campaignId: Campaign ID to be shown

Prior to the user's interaction with the partner apps in their feed, they are required to agree to the AppsPrize Terms of Service. Additionally, they have the option to grant your app permission to track the usage of other apps on their phone through the device settings.

You can use the hasPermissions function.

Kotlin

@JvmStatic
fun hasPermissions(context: Context): Boolean

This function allows you to check for permission status to track rewards.

Return

Permission status

Parameters

context: Activity context

requestPermission allows you to manually request permission to track rewards. If permission is not available, it forwards to Android settings.

Kotlin

@JvmStatic
fun requestPermission(context: Context): Boolean

Return

Permission status

Parameters

context: Activity context

Rewarding

You can use the AppReward class for managing a reward with completed levels.

AppReward

Kotlin

data class AppReward(val rewards: List<RewardLevel>)

This class represents an App reward with completed levels.

Constructors

AppReward

Kotlin

AppReward(rewards: List<RewardLevel>)

Properties

Kotlin

val rewards: List<RewardLevel>

Completed list of reward levels.

RewardLevel

Kotlin

public data class RewardLevel(
    val level: Int,
    val points: Int,
    val currency: String,
)

This class represents a reward level.

Constructors

RewardLevel

Kotlin

RewardLevel(level: Int, points: Int, currency: String)

Properties

currency
Kotlin
```
val currency: String
```

> Currency used for giving reward

level
Kotlin
```
val level: Int
```

> Level number

points
Kotlin
```
val points: Int
```

> Points earned at the level

In order to understand if the user has completed one or multiple rewards in a session, you can call onRewardUpdate function.

Kotlin

open fun onRewardUpdate(rewards: List<AppReward>)

Parameters

rewards: List of rewards earned by user

Payout

To enable users to claim their accumulated rewards, they need to receive a payout. Each reward can be redeemed only once.

Server-to-server Payout

To utilize server-to-server payout, you should establish an endpoint on your server, which we can trigger to inform you about the install and user's rewards . Upon receiving this notification, the responsibility of delivering the rewards to the user lies with you.

We strongly advise adopting the server-to-server payout method for rewards due to its enhanced security and improved transparency on your side.

Endpoint Structure

Once you share your endpoint URL, we will useHTTP POST request in order to send callback to your side. We will set the below query parameters and fill statically once an install occurs. You need to parse the parameters and handle on your side.

Parameter	Description	Format	Type
user_id	Unique client app's user ID	string	mandatory
coin_currency	currency name of client app	string	mandatory
coin_amount	Total number of reward amount that will be earned by the users when they completed whole levels	float	mandatory
cpi_bid	offer cpi/cpa bid	float	mandatory
payout_currency	currency of offer cpi bid (USD)	string	mandatory
device_id	advertising ID of end-user from install	string	optional
trans_id	The unique transaction ID	UUID v4	mandatory
sig	Signature that should be verified request authenticity. It's a SHA256 hash code of the calculation of the request parameters as sig=SHA256(concatenate(trans_id,user_id,coin_amount,coin_currency ,app_token,s2s_token)	string	mandatory
event_name	Exact event name coming from advertiser/offer's app	string	mandatory
event_token	Event description	string	mandatory
event_coin_amount	The reward amount that will be earned by the users when they completed an event/task.	float	mandatory
app_bundle_id	Advertiser/offer's app bundle id	string	optional
app_name	Advertiser/offer's app name	string	optional
level	It refers to play time level or daily quests	string	optional
seconds	Playing and spending time in advertiser app	string	optional
points	Reward Amount that is earned by the users as long as they play and spend time in advertiser app.	string	mandatory
currency	Publisher Currency Name	string	optional
type	Type of Postback Request (install, reward or event)	string	mandatory

In order to be ensure that the callback requests are coming from us, you need to calculate the sig parameter and compare with the parameters which are sent by the callback request. Calculation is; sig=SHA256(concatenate(trans_id,user_id,coin_amount,coin_currency ,app_token,s2s_token).

Once you share the main endpoint S2S URL, s2s_token will be generated and given to you.

We will make POST requests whenever a user installs and open the apps, also completes a reward level separately.

Sample Body for Install Request (for both type of campaigns, time or task based)

Kotlin

{
  "app_bundle_id": "com.oakgames.linked2248.numberpuzzle",
  "app_name": "2248: Number Puzzle Game",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 0.15,
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "36097a85-5e1b-44b6-8966-0e2e226b7a0",
  "type": "install",
  "user_id": "test1"
}

For task based offers, you will receive "cpi_bid":0in install type postback requests.

Sample Body for Rewards (for Time Based Campaigns)

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "rewards":[ 
    {
      "level": 1,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 2,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 3,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    }
  ],
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "4a66188d-4278-487d-8953-b33c0c85ff9f",
  "type": "reward",
  "user_id": "test1"
}

Sample Body for Daily Quest Rewards (for Time Based Campaigns)

It looks like time based rewards body, but difference is "level"will come with "daily-quest".

Kotlin

 {
		"sig": "1a052ed124335b0bfdfb7afd205a61c5e8046b6cad8d06ced1151d92effe1",
		"type": "reward",
		"rewards": {
			"level": "daily-quest",
			"points": 83,
			"seconds": 120,
			"currency": "Points"
		},
		"user_id": "test_user",
		"app_name": "Cornhole League",
		"trans_id": "1658e4b0-1d98-4d17-9535-95124df40e54",
		"coin_amount": 0,
		"app_bundle_id": "com.sport.cornhole",
		"coin_currency": "USD"
	},

Sample Body for In-app Events/Tasks (for Task based Campaigns)

For some offers, we can add additional special offer section such as in-app purchase events, in this situation we will send postback with "cpi_bid":0. Only you need to use event_coin_amount in these requests in order to reward the user.

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 9,
  "event_coin_amount": 27000,
  "event_name": "Level_5",
  "event_token": "Reach Level 5",
  "sig": "a65d72b215160e643058659089558c6d35c55717277b33c6becd7e403bfd31fb",
  "trans_id": "70660187-93cf-40eb-8cce-f9ce22fc46e2",
  "type": "event",
  "user_id": "test1"
}

Requests for reward levels

The reward postback will not be received until the end user returns to the SDK from the app they played. As the playtime in the downloaded app is completed, the rewards of the corresponding level will be postbacked.

The HTTP 200 OKsuccessful response status code indicates that a request has succeeded.

Payout via SDK

We recommend that you use the server-to-server payout model for better security and transparency, but if you cannot handle the server requests on your side, you can call the doReward function as below.

We will handle the reward payouts inside the SDK itself by this method.

To pay out the rewards that the user has collected from advertiser apps directly in the SDK, call

Java

AppsPrize.doReward(MainActivity.this, new AppsPrizeRewardListener() {
    @Override
    public void onSessionReward(List<AppReward> list) {
        // used for handling session reward without AppsPrizeListener.onRewardUpdate event method
    }
});

Kotlin

AppsPrize.doReward(this) { sessionReward ->
    // used for handling session reward without AppsPrizeListener.onRewardUpdate event method
}

Using the SDK

Once you have set up and initialized the SDK you can use its features:

AppsPrize Offerwall Access

The Offerwall feed comprises apps that users can install and utilize to earn rewards. This feed is presented in a distinct activity.

In order to launch AppsPrize, call:

JavaScript

AppsPrize.launch()

This function allows you to launch AppsPrizeActivity to show available campaigns and track apps' reward progress. If AppsPrize is not initialized, it returns false.

For the launch options;

You can set the type to be opened in offerwall, Only Time Based or Task Based. So you will be able to show specific offerwall type for different placements as well.

Kotlin

AppsPrize.launch({type: "all" | "only_time" | "only_task"})

JavaScript

AppsPrize.open(campaignId)

This function allows you to open directly detail page given campaign ID. If AppsPrize not initialized returns false.

You can use the hasPermissions function.

JavaScript

AppsPrize.hasPermissions()
            .then(has => console.log(`AppsPrize:TS:hasPermissions - ${has}`))
            .catch(err => console.log(`AppsPrize:TS:hasPermissions - ${err}`))

This function allows you to check for permission status to track rewards.

requestPermission allows you to manually request permission to track rewards. If permission is not available, it forwards to Android settings.

JavaScript

AppsPrize.requestPermission()
            .then(has => console.log(`AppsPrize:TS:requestPermission - ${has}`))
            .catch(err => console.log(`AppsPrize:TS:requestPermission - ${err}`))

Payout

To enable users to claim their accumulated rewards, they need to receive a payout. Each reward can be redeemed only once.

Server-to-server Payout

To utilize server-to-server payout, you should establish an endpoint on your server, which we can trigger to inform you about the user's rewards. Upon receiving this notification, the responsibility of delivering the rewards to the user lies with you.

We strongly advise adopting the server-to-server payout method for rewards due to its enhanced security and improved transparency on your side.

Endpoint Structure

Once you share your endpoint URL, we will useHTTP POSTrequest in order to send callback to your side. We will set the below query parameters and fill statically once an install occurs. You need to parse the parameters and handle on your side.

Parameter	Description	Format	Type
user_id	Unique client app's user ID	string	mandatory
coin_currency	currency name of client app	string	mandatory
coin_amount	Total number of reward amount that will be earned by the users when they completed whole levels	float	mandatory
cpi_bid	offer cpi/cpa bid	float	mandatory
payout_currency	currency of offer cpi bid (USD)	string	mandatory
device_id	advertising ID of end-user from install	string	optional
trans_id	The unique transaction ID	UUID v4	mandatory
sig	Signature that should be verified request authenticity. It's a SHA256 hash code of the calculation of the request parameters as sig=SHA256(concatenate(trans_id,user_id,coin_amount,coin_currency ,app_token,s2s_token)	string	mandatory
event_name	Exact event name coming from advertiser/offer's app	string	mandatory
event_token	Event description	string	mandatory
event_coin_amount	The reward amount that will be earned by the users when they completed an event/task.	float	mandatory
app_bundle_id	Advertiser/Offer's app bundle id	string	optional
app_name	Advertiser/Offer's app name	string	optional
level	It refers to play time level or daily quests	string	optional
seconds	Playing and spending time in advertiser app	string	optional
points	Reward Amount that is earned by the users as long as they play and spend time in advertiser app.	string	mandatory
currency	Publisher Currency Name	string	optional
type	Type of Postback Request (install, reward or event)	string	mandatory

Once you share the main endpoint S2S URL, s2s_token will be generated and given to you.

We will make POST requests whenever a user installs and open the apps, also completes a reward level separately.

Sample Body for Install Request (for both type of campaigns, time or task based)

Kotlin

{
  "app_bundle_id": "com.oakgames.linked2248.numberpuzzle",
  "app_name": "2248: Number Puzzle Game",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 0.15,
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "36097a85-5e1b-44b6-8966-0e2e226b7a0",
  "type": "install",
  "user_id": "test1"
}

For task based offers, you will receive "cpi_bid":0in install type postback requests.

Sample Body for Rewards (for Time Based Campaigns)

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "rewards":[ 
    {
      "level": 1,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 2,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 3,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    }
  ],
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "4a66188d-4278-487d-8953-b33c0c85ff9f",
  "type": "reward",
  "user_id": "test1"
}

Sample Body for Daily Quest Rewards (for Time Based Campaigns)

It looks like time based rewards body, but difference is "level" will come with "daily-quest".

Kotlin

{
		"sig": "1a052ed124335b0bfdfb7afd205a61c5e8046b6cad8d06ced1151d92effe1",
		"type": "reward",
		"rewards": {
			"level": "daily-quest",
			"points": 83,
			"seconds": 120,
			"currency": "Points"
		},
		"user_id": "test_user",
		"app_name": "Cornhole League",
		"trans_id": "1658e4b0-1d98-4d17-9535-95124df40e54",
		"coin_amount": 0,
		"app_bundle_id": "com.sport.cornhole",
		"coin_currency": "USD"
	},

Sample Body for In-app Events/Tasks (for Task based Campaigns)

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 9,
  "event_coin_amount": 27000,
  "event_name": "Level_5",
  "event_token": "Reach Level 5",
  "sig": "a65d72b215160e643058659089558c6d35c55717277b33c6becd7e403bfd31fb",
  "trans_id": "70660187-93cf-40eb-8cce-f9ce22fc46e2",
  "type": "event",
  "user_id": "test1"
}

The HTTP 200 OKsuccessful response status code indicates that a request has succeeded.

Payout via SDK

We will handle the reward payouts inside the SDK itself by this method.

To pay out the rewards that the user has collected from advertiser apps directly in the SDK, call

JavaScript

AppsPrize.doReward((rewards) => {
            console.log(`AppsPrize:TS:doReward - ${JSON.stringify(rewards)}`)
          })

Using the SDK

Once you have set up and initialized the SDK you can use its features:

AppsPrize Offerwall Access

The Offerwall feed comprises apps that users can install and utilize to earn rewards. This feed is presented in a distinct activity.

In order to launch playtime, call:

AppsPrize.Launch()

This function allows you to launch AppsPrizeActivity to show available campaigns and track apps' reward progress. If AppsPrize is not initialized, it returns false.

For the launch options;

You can set the type to be opened in offerwall, Only Time Based or Task Based. So you will be able to show specific offerwall type for different placements as well.

AppsPrize.Launch(new AppsPrizeOfferwallOptions(
		type: /**  AppsPrizeOfferwallOptionType.ALL | AppsPrizeOfferwallOptionType.ONLY_TIME | AppsPrizeOfferwallOptionType.ONLY_TASK */
	)
);

AppsPrize.Open(campaignId)

This function allows you to open directly detail page given campaign ID. If AppsPrize not initialized returns false.

You can use the HasPermissions function.

AppsPrize.HasPermissions();

This function allows you to check for permission status to track rewards.

RequestPermission allows you to manually request permission to track rewards. If permission is not available, it forwards to Android settings.

AppsPrize.RequestPermission();

Payout

To enable users to claim their accumulated rewards, they need to receive a payout. Each reward can be redeemed only once.

Server-to-server Payout

We strongly advise adopting the server-to-server payout method for rewards due to its enhanced security and improved transparency on your side.

Endpoint Structure

Once you share your endpoint URL, we will useHTTP POSTrequest in order to send callback to your side. We will set the below query parameters and fill statically once an install occurs. You need to parse the parameters and handle on your side.

Parameter	Description	Format	Type
user_id	Unique client app's user ID	string	mandatory
coin_currency	currency name of client app	string	mandatory
coin_amount	Total number of reward amount that will be earned by the users when they completed whole levels	float	mandatory
cpi_bid	offer cpi/cpa bid	float	mandatory
payout_currency	currency of offer cpi bid (USD)	string	mandatory
device_id	advertising ID of end-user from install	string	optional
trans_id	The unique transaction ID	UUID v4	mandatory
sig	Signature that should be verified request authenticity. It's a SHA256 hash code of the calculation of the request parameters as sig=SHA256(concatenate(trans_id,user_id,coin_amount,coin_currency ,app_token,s2s_token)	string	mandatory
event_name	Exact event name coming from advertiser/offer's app	string	mandatory
event_token	Event description	string	mandatory
event_coin_amount	The reward amount that will be earned by the users when they completed an event/task.	float	mandatory
app_bundle_id	Advertiser/Offer's app bundle id	string	optional
app_name	Advertiser/Offer's app name	string	optional
level	It refers to play time level or daily quests	string	optional
seconds	Playing and spending time in advertiser app	string	optional
points	Reward Amount that is earned by the users as long as they play and spend time in advertiser app.	string	mandatory
currency	Publisher Currency Name	string	optional
type	Type of Postback Request (install, reward or event)	string	mandatory

Once you share the main endpoint S2S URL, s2s_token will be generated and given to you.

We will make POST requests whenever a user installs and open the apps, also completes a reward level separately.

Sample Body for Install Request (for both type of campaigns, time or task based)

Kotlin

{
  "app_bundle_id": "com.oakgames.linked2248.numberpuzzle",
  "app_name": "2248: Number Puzzle Game",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 0.15,
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "36097a85-5e1b-44b6-8966-0e2e226b7a0",
  "type": "install",
  "user_id": "test1"
}

For task based offers, you will receive "cpi_bid":0in install type postback requests.

Sample Body for Rewards (for Time Based Campaigns)

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "rewards":[  
    {
      "level": 1,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 2,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    },
    {
      "level": 3,
      "seconds": 60,
      "points": 18,
      "currency": "Points"
    }
  ],
  "sig": "5d775fa8d601ffdea8a65fd0225e0637d2b87b57072483dd0dcc49aa735c9b", // (trans_id, user_id, coin_amount, coin_currency, app_token, s2s_token)
  "trans_id": "4a66188d-4278-487d-8953-b33c0c85ff9f",
  "type": "reward",
  "user_id": "test1"
}

Sample Body for Daily Quest Rewards (for Time Based Campaigns)

It looks like time based rewards body, but difference is "level" will come with "daily-quest".

Kotlin

{
		"sig": "1a052ed124335b0bfdfb7afd205a61c5e8046b6cad8d06ced1151d92effe1",
		"type": "reward",
		"rewards": {
			"level": "daily-quest",
			"points": 83,
			"seconds": 120,
			"currency": "Points"
		},
		"user_id": "test_user",
		"app_name": "Cornhole League",
		"trans_id": "1658e4b0-1d98-4d17-9535-95124df40e54",
		"coin_amount": 0,
		"app_bundle_id": "com.sport.cornhole",
		"coin_currency": "USD"
	},

Sample Body for In-app Events/Tasks (for Task based Campaigns)

Kotlin

{
  "app_bundle_id": "com.sport.cornhole",
  "app_name": "Cornhole League",
  "coin_amount": 10000,
  "coin_currency": "USD",
  "cpi_bid": 9,
  "event_coin_amount": 27000,
  "event_name": "Level_5",
  "event_token": "Reach Level 5",
  "sig": "a65d72b215160e643058659089558c6d35c55717277b33c6becd7e403bfd31fb",
  "trans_id": "70660187-93cf-40eb-8cce-f9ce22fc46e2",
  "type": "event",
  "user_id": "test1"
}

The HTTP 200 OKsuccessful response status code indicates that a request has succeeded.

Payout via SDK

We recommend that you use the server-to-server payout model for better security and transparency, but if you cannot handle the server requests on your side, you can call the DoReward function as below.

We will handle the reward payouts inside the SDK itself by this method.

To pay out the rewards that the user has collected from advertiser apps directly in the SDK, call

AppsPrize.DoReward(OnCurrentRewardUpdate);

public void OnCurrentRewardUpdate(List<AppRewards> rewards)
{
    Debug.Log("OnCurrentRewardUpdate");
}

Next step

To match the offerwall to your app's look, see UI customization.