A New Way to Monetize and Engage

Maximize your app’s revenue and engagement effortlessly with the Playtime SDK, adjoe’s mobile-games-centric rewarded ad unit. Integrate it within your app, and start rewarding users with your in-app currency for playing advertised mobile games.

Playtime taps into your users' love for gaming, offering you industry-leading eCPM and engagement metrics in return. To learn more about how adjoe can boost your app's monetization, engagement, and retention, click here.

Now, let's move on to explore how to set up and integrate the SDK.

Supported Wrappers

Requirements

• Android 16+

• Gradle 7.2.2+

• minSdkVersion 16+

• compileSdkVersion 23+

Maximize your app’s revenue and engagement effortlessly with Playtime - adjoe’s mobile-games-centric rewarded ad unit for Android and iOS. Integrate it within your app, and start rewarding users with your in-app currency for playing advertized mobile games.

We offer a native SDK solution for Android and a web-based option for iOS. Playtime seamlessly integrates with our Reporting APIs, allowing you to track your KPIs, monitor Playtime's performance, and achieve your revenue targets. Select your preferred platform and get started!

Ensure an issue-free integration and launch of the Playtime SDK with this all-in-one setup and rollout checklist.

Integration

• SDK Hash received from Account Manager.

• Access to Publisher Dashboard confirmed.

• Test Devices set up in the Publisher Dashboard with GAIDs.

• Playtime SDK dependency integrated into the app.

• Logs Enabled (Native Only).

• SDK initialized at app start without errors.

• Playtime.Options() invoked with init and includes userId, playtimeParams, playtimeUserProfile, and playtimeExtensions.

• SDK initialization verified using Playtime.isInitialized.

• SDK is re-initialized upon the app going into foreground (in onResume or didChangeAppLifecycleState) without errors.

• Teaser event integrated and communicated to adjoe.

• Playtime Catalog launch setup completed.

• Server endpoint prepared on your servers for S2S payouts.

• The s2s_token for S2S payouts received from Account Manager.

• The sid verified and matches the parameter sent in the callback from adjoe.

• IP-Level blocking implemented.

Launch

• App IDs remain unchanged and the SDK Hash remains tied to the same app ID.

• Separate app IDs used for test (sandbox) and production (dev) environments.

• Sever endpoint for S2S payouts verified and tested. Successful payouts are confirmed.

• Application rollout initiated with a small percentage of users.

Follow this guide to configure your app to work with the Playtime SDK using any of our supported wrappers.

Step 1. Get Your SDK Hash

Contact your Account Manager to get an SDK hash for your app. Or if you already have access, it can be retrieved from the Publisher Dashboard.

The SDK hash is a unique 32-character code that uniquely identifies your app within adjoe's systems. Each app receives a distinct hash. Remember to keep your hash confidential to prevent unauthorized use.

Step 2. Add Test Devices

To fully test the Playtime SDK integration and access all campaign types, configure your physical devices and emulators as test devices. Without this step, the types of available campaigns you get will be limited when using VPNs or emulators.

1. Find Your GAID (Google Advertising ID):

• Open the Settings app or Google settings (depends on your device).

• Go to "Google" > "Ads" in the Services section.

• Your GAID is displayed at the bottom.

1. Register as a Test User:

• With your GAID, go to the Publisher Dashboard. If you don't have dashboard access, contact your Account Manager.

• In the dashboard, find "Test Users" under configuration settings and enter your GAID.

Step 3. Add the Playtime SDK Dependency

allprojects {
    repositories {
        ...
        maven {
            url  "https://releases.adjoe.io/maven"
        }
    }
}

dependencies {
    ...
    implementation 'io.adjoe:adjoe-sdk-android:3.0.0'
}

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://releases.adjoe.io/maven") }
    }
}

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://releases.adjoe.io/maven") 
        }
    }
}

dependencies {
    ...
    implementation 'io.adjoe:adjoe-sdk-android:3.0.0'
}

dependencies: {
  "react-native-adjoe-sdk": "https://github.com/adjoeio/adjoe-react-native-sdk#v3.0.0"
}

allprojects {
    repositories {
        maven {
            url  "https://releases.adjoe.io/maven"
        }
    }
}

npm install

dependencies:
  adjoe:
    git:
      url: https://github.com/adjoeio/adjoe-flutter-sdk
      ref: v3.0.0

dependencies: {
  "cordova-plugin-adjoe": "https://github.com/adjoeio/adjoe-cordova-sdk#v3.0.0"
}

npm install

Step 4: Enable Logs (Native only)

Enabling logging per device within the SDK is crucial for troubleshooting. Turn on logging and include the logs with any bug reports to help us accurately replicate and address issues.

Here’s how to enable logging:

1. Connect the device to your computer and enable ADB.

2. In a terminal window, run the following command to activate logging:

adb shell setprop log.tag.Playtime INFO

You can now filter LogCat using the Playtime tag to monitor relevant log output. If you wish to disable logging, simply execute the command:

adb shell setprop log.tag.Playtime ERROR

This sets the logging level to ERROR, effectively reducing the verbosity of the logs.

Once a user meets the criteria for being rewarded, it's time to initiate the payout—sending the rewards to the user. Publishers issue these payouts upon receiving a payout request callback from adjoe's backend. The request is made to the S2S API URL configured for the publisher for their SDK in the Publisher Dashboard.

Set Up Server-to-Server (S2S) Payouts

To enable S2S payouts, set up an endpoint on your server to receive notifications about user rewards from adjoe. When a request is made to your endpoint, you then must manage the distribution of these rewards to the users. Be aware that once a reward is distributed, it cannot be allocated again.

Endpoint Structure

The key names can be customized, or you can use the default names. Please ensure that no special characters should be included in the values, otherwise our backend may transform the request, which could cause issues with the payout. Some of these values include: [] . =

Default

GET / https://example.com/example?sid={sid}&trans_uuid={trans_uuid}&user_uuid={user_uuid}&currency={currency}&coin_amount={coin_amount}&device_id={device_id}&sdk_app_id={sdk_app_id}&app_id={app_id}&reward_level={reward_level}&app_name={app_name}&reward_type={reward_type}&publisher_sub_id1={publisher_sub_id1}&publisher_sub_id2={publisher_sub_id2}&publisher_sub_id3={publisher_sub_id3}&publisher_sub_id4={publisher_sub_id4}&publisher_sub_id5={publisher_sub_id5}&placement={placement}&ua_network={ua_network}&ua_channel={ua_channel}&ua_subpublisher_encrypted={ua_subpublisher_encrypted}&ua_subpublisher_cleartext={ua_subpublisher_cleartext}

Customized (Example)

GET / https://example.com/example?user_id={user_uuid}&sid={sid}&point_amount={coin_amount}&points={currency}&trans_uuid={trans_uuid}&ua_network={ua_network}&ua_channel={ua_channel}&playtime_placement={placement}&custom_id={publisher_sub_id1}

Example Response URL:

https://s2sexamplerequestendpoint.com/payout?user_uuid=a79d7158-6f9c-4e5b-ae7a-98143c77d396&sid=0de7e36d2965269f172d2d89bc9a8026da7f0819&coin_amount=100&currency=dollars&trans_uuid=e7b1a95f-8c72-4ed8-af69-ecf8d06b1d89&sdk_app_id=example.test.app&ua_network=tiktok&ua_channel=direct&publisher_sub_id1=RandomString

Calculate the SID

sid = sha1(concatenate(trans_uuid, user_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token))

If sdk_app_id and/or device_id are not present in the endpoint URL, they will be excluded from the sid calculation. The sid will then be calculated as follows:

sid = sha1(concatenate(trans_uuid, user_uuid, currency, coin_amount, s2s_token))

Below is an example script that shows how to calculate the sid and compare it to the value in the callback URL sent by adjoe. You would implement some version of this in your backend.

import hashlib
from urllib.parse import urlparse, parse_qs

def calculate_sid(user_uuid, trans_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token):
    data = ''.join([trans_uuid, user_uuid, currency, str(coin_amount), device_id, sdk_app_id, s2s_token])
    hashed_data = hashlib.sha1(data.encode()).hexdigest()
    return hashed_data

def extract_parameters(url):
    parsed_url = urlparse(url)
    query_params = parse_qs(parsed_url.query)
    return query_params

def compare_sids(url, calculated_sid):
    query_params = extract_parameters(url)
    sid_from_url = query_params.get('sid', [None])[0]
    return sid_from_url == calculated_sid

# Example URL
url = "https://s2sexamplerequestendpoint.com/payout?user_uuid=a79d7158-6f9c-4e5b-ae7a-98143c77d396&sid=2477185c00a5b1ac94fdf94798798d5e846d8aee&coin_amount=100&currency=dollars&trans_uuid=e7b1a95f-8c72-4ed8-af69-ecf8d06b1d89&device_id=9a7e993a-80b4-4c3b-832f-97a5f501e2f1&sdk_app_id=com.example.android.gamename&ua_network=tiktok&ua_channel=direct&publisher_sub_id1=RandomString"

# Extract parameters from URL
query_params = extract_parameters(url)
user_uuid = query_params.get('user_uuid', [None])[0]
sid = query_params.get('sid', [None])[0]
trans_uuid = query_params.get('trans_uuid', [None])[0]
currency = query_params.get('currency', [None])[0]
coin_amount = int(query_params.get('coin_amount', [None])[0])
device_id = query_params.get('device_id', [None])[0]
sdk_app_id = query_params.get('sdk_app_id', [None])[0]
s2s_token = " " #the s2s_token will be supplied by your Account Manager.

# Calculate SID
calculated_sid = calculate_sid(user_uuid, trans_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token)

# Compare SIDs
result = compare_sids(url, calculated_sid)
print("SID Comparison Result:", result)

S2S Security

When we make payout request to publishers, we send an HTTP request from any of the following IP addresses:

3.121.65.44
18.185.166.67
52.29.52.48

To enhance security, use these IP addresses for IP-level blocking on endpoints receiving adjoe's S2S payout requests. Allow only these specific IPs access.

Retry Logic

If we receive a 4xx / 5xx from your endpoint, we have an established retry logic for the failed S2S requests.

If a request fails, we retry after 10 minutes. A second failure prompts a retry in another 10 minutes. Subsequent failures lead to retries every 2 hours from the initial failed attempt. The time windows are additional, so it's roughly 12hrs in total.

Testing Payouts

Follow these steps to verify the correct functioning of payouts:

1. Install games from the catalog, include "event-based" and "time-based" campaigns.

2. Play the games and complete the tasks required to earn rewards (e.g., finishing a task or playing for a specific duration).

3. Verify that the completed tasks are reflected in the game's reward card.

4. Ensure that the earned rewards, such as points, are credited to the app's wallet. For example, if you completed a task for 5 points, check that these points are available in the wallet.

5. Confirm that a 200 status code is logged in your records. Anything other than a 200 status code means that your endpoint has not been configured correctly to receive requests from adjoe.

Best Practices for Rewarding Users

If you payout with real money, we recommend that you implement KYC processes, reward cooldowns, and individual limits on the amount of rewards the user can get:

• Reward Cooldowns: Temporarily restrict users from receiving additional rewards after receiving one. This helps maintain fairness and prevents exploitation of the rewards system, like receiving rewards too frequently.

• Individual Limits: To prevent abuse of the rewards systems, set daily limits on the amount of rewards a user can earn. For example, you might cap rewards at $50 USD per day.

Playtime SDK

Is it necessary to provide the userId at app start-up with the init method?

No. Since the init method should happen at app start-up, there are circumstances where you don’t yet have this data. For example, if the user hasn’t signed in yet. In these cases, it’s still critical to init at the app start up, but you can pass in the UA Params or User ID in an OnResume / AppState / didChangeAppLifecycleState function when you have the data.

Remember that the userId is critical for doing S2S payouts, without it your users will not be able to get their rewards. It is also important to note that whatever the last supplied userId was is what will be sent in the S2S payout URL. Therefore, the last supplied User ID was is what will be sent in the S2S payout URL.

Do I need to do anything with the Playtime SDK after the user logs out?

No. But if the user can only access the Playtime Catalog after logging-in, then you should remove any calls to init when they log out.

What is the size of SDK?

SDK size depends on the wrapper, but it is roughly <0.5MB.

Can I show the adjoeActivity in a Fragment?

No, this is not supported.

How often is the SDK updated?

The SDK is updated every couple of months. Please keep an eye out on our .

What kind of data does the SDK track? I need to share this information with the Google Play Store.

All of the data that we collect can be found in the AndroidManifest.xml of the SDK.

How do users know that they are able to receive a reward?

For Android users, we show a toast message on the top of the screen whenever a user is able to receive a reward.

I'm using Flutter or React Native - how can I use your Android SDK and iOS solution together?

Yes, you can use the Platform properties provided by the Flutter and React Native libraries to set up the code in a way to conditionally execute certain code blocks based on the platform the app is running on. Since we only have an SDK on Android, you may need to use platform-based imports for RN or add platform-specific dependencies in the pubspec.yaml for Flutter.

Example for React Native:

const showPlaytimeCatalog = async () => {
  if (Platform.OS === 'ios') {
    return navigation.navigate('InAppBrowser', {
      url: `https://{your_company_name}.playtimeweb.com/play?user_id={user_id}&idfa={IDFA}`
    });
  }

  if (playtimeInitialized && Platform.OS === 'android') {
    return await Playtime.showCatalog().catch(err => {
      console.error(`Could not show Playtime catalog: ${err}`);
    });
  }
};

Using the Playtime Catalog

I'm not seeing campaigns/games in the catalog?

The most common reason this happens is because of VPN usage. If you use a VPN, you might not see any campaigns, even if you set yourself as a test user. We still filter out IP addresses that are anonymous.

After playing some time-based reward games, I stopped receiving rewards after 15 mins. Why?

It can happen because you stopped progressing through the game. To fix this, please keep playing and progressing through the game.

What's the difference between time-based and event-based campaigns?

What is the use of the GAID?

Why does the user need to accept Access to Advertising Info?

Why does the user need to accept TOS?

We hereby inform you that adjoe GmbH processes the following personal data within the framework of the use of Playtime:

• Installed apps (including the use duration and use history)

The data will be connected to your end device via the device ID and sent, encrypted, to our servers. In order for app providers to finance our app suggestions, we must send them the device ID for billing purposes.

The processing of the above data is necessary to be able to recommend, via system messages, the installation of apps available in Playtime that match your interests, and calculate the bonuses acquired as a result of your use of the corresponding apps.

Consent

By clicking on ACCEPT, I give adjoe GmbH my consent to process my above-mentioned personal data and transmit it to other app providers so that I can use Playtime as described.

I am aware that a profile of interests will be generated using the above data, and depending on the types of apps I use, this may contain particularly sensitive personal data (e.g. health-related data or data about my sexual orientation, and any other data in special categories pursuant to Art. 9[1] GDPR). For that reason my consent also applies explicitly to the processing of this data. The full links to our Data Privacy Statement and Terms and Conditions of use are available here and here respectively.

Business

How do I give one of my coworkers access to the dashboard?

You should reach out to your Account Manager. They can provide them with access.

What customization options do you provide for the Playtime Catalog?

Most parts of the Playtime Catalog can be customized so that it fits your branding - including images, colors, texts, fonts, and currency. Your Account Manager will reach out to you separately to set up these customizations.

Where can I track KPIs like Revenue or Active User Rates?

Solve any SDK issues quickly with this guide, covering common errors and setup problems. For more help or to suggest features, find support contact details below.

Troubleshoot Common Issues

Operation fails with the exception "not available for this user".

Your device has been blocked. If your device was previously configured as a test device, please inform us so we can address the issue. If not, follow these steps:

1. Uninstall the app containing the SDK. Ensure its data is also removed from any automatic backups.

2. Reset your GAID: Go to Settings > Google > Ads and tap on Reset Ad-ID.

3. using the new GAID.

You don't see any games in the catalog.

Your device may be blocked. Proceed as described in the issue above.

Notification of reward received, but the SDK does not display the new rewards.

Check your device's time setting; incorrect time (e.g., set to the future or past) often causes this. If the time is correct and the issue persists, contact us and we will investigate this issue.

App compilation fails with "Duplicate class" or "Duplicate entry" exceptions.

This can happen when Gradle cannot resolve a dependency conflict, such as when two dependencies use the same transitive dependency but with different versions. To resolve this conflict you must either:

• Remove one of the conflicting dependencies.

• Align the versions of the conflicting dependencies to match.

If the affected dependency is one of your app's dependencies, simply adjust or remove it from the dependencies list in your build.gradle. If the affected dependency is transitive, you must exclude it from the dependency which specifies it as a transitive dependency.

Duplicate class due to androidx.work:work-runtime:$workVersion.

Our SDK supports pre-AndroidX projects, so we are using the work-runtime library that predates AndroidX. There is an issue with the Android Gradle plugin <3.6.0 where the Jetifier does not correctly replace the dependency. If you are not already using a supported version of Gradle, you need to bump the version in your root project's build.gradle file.

buildscript {

    repositories {
        google()
        mavenCentral()
        ...
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.6.0' // Set this to 3.6.0 or higher.
        ...
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

Please also ensure that you have enabled the Jetifier by placing the line android.enableJetifier=true into your gradle.properties file.

If you continue to have issues due to a conflict between the versions of the androidx.work:work-runtime library in your project, you can fix this issue by adding the following to your app level build.gradle file.

configurations.all {

    resolutionStrategy.dependencySubstitution {
        // Substitute one module dependency for another
        substitute module('android.arch.work:work-runtime:1.0.1') with module('androidx.work:work-runtime:2.0.1')
    }

    resolutionStrategy.force 'androidx.work:work-runtime:2.0.1'
}

dependencies {
    implementation 'androidx.work:work-runtime:2.0.1'
   ....
}

The currently supported version of work-runtime is up to 2.0.1

Get Further Support

Still need help with something? Have an idea for a Feature Request? Please use this template to reach out to your Account Manager for help.

• Issue Type: [Bug/Feature Request]

• Framework: [Android/Flutter/React Native/Unity/Cordova]

• SDK Version:

• Priority: [High/Medium/Low]

• Crash: [Yes/No]

  • Devices Affected: (e.g., Samsung, Pixel)

  • User Impact: Number or percentage

  • Environment: [Production/Test]

• Issue/Feature Description: Provide a detailed description. For feature requests, explain the necessity and potential business impact.

• Reproduction Steps:

• Expected Behavior:

• Actual Behavior:

Please include any relevant logs, crash reports, API calls, or screenshots to support your query.

A New Way to Monetize and Engage

Maximize your app’s revenue and engagement effortlessly with PlaytimeWeb for iOS, adjoe’s mobile-games-centric rewarded ad unit. Integrate it within your app, and start rewarding users with your in-app currency for playing advertised mobile games.

Playtime taps into your users' love for gaming, offering you industry-leading and engagement metrics in return. To learn more about how adjoe can boost your app's monetization, engagement, and retention, click .

Integrate PlaytimeWeb

To seamlessly integrate PlaytimeWeb into your iOS app, you only need to offer users the option to open the PlaytimeWeb URL. We suggest placing this option prominently in your app, such as in a native banner or button on the homepage. The basic structure of the Redirect URL is:

https://{your_company_name}.playtimeweb.com/play?user_id={user_id}&idfa={IDFA}

The user_id and idfa parameters in the URL help accurately identify the user for rewarding purposes, ensuring any currency earned via PlaytimeWeb is promptly paid out.

Supported URL Parameters

Accept Tracking

Use a WebView

A WebView or SFSafariViewController or iFrame can be used to show the PlaytimeWeb URL. You may need to configure the navigation actions to open the app-store URL, as the webView may have it's own protocols for intercepting the URL requests.

• Allow the following url-schemes

  1. https

  2. itms-appss

  3. itms-apps

  4. about:srcdoc

Test the Integration

1. Open PlaytimeWeb from your app.

2. Download a game.

3. Return to PlaytimeWeb. You should see the game under the "My Games" section.

4. If you do not see the game in "My Games" try resetting your IDFA.

Reset the IDFA

1. Delete the game if it was already installed.

2. Go to Settings > Privacy > Tracking, toggle Allow Apps to Request to Track off.

3. Return to PlaytimeWeb and select Ask Apps to Stop Tracking (if prompted), then toggle Allow Apps to Request to Track back on.

4. Install the game again from PlaytimeWeb.

Once a user meets the criteria for rewards, it's time to initiate the payout—sending the rewards to the user. Publishers issue these payouts upon receiving a payout request callback from adjoe's backend. The request is made to the S2S API URL configured for the publisher for their SDK in the Publisher Dashboard.

Set Up Server-to-Server (S2S) Payouts

To enable S2S payouts, set up an endpoint on your server to receive notifications about user rewards from adjoe. When a request is made to your endpoint, you then must manage the distribution of these rewards to the users. Be aware that once a reward is distributed, it cannot be allocated again.

Endpoint Structure

The key names can be customized, or you can use the default names. Please ensure that no special characters should be included in the values, otherwise our backend may transform the request, which could cause issues with the payout. Some of these values include: [] . =

Default

GET / https://example.com/example?sid={sid}&trans_uuid={trans_uuid}&user_uuid={user_uuid}&currency={currency}&coin_amount={coin_amount}&device_id={device_id}&sdk_app_id={sdk_app_id}&app_id={app_id}&reward_level={reward_level}&app_name={app_name}&reward_type={reward_type}&publisher_sub_id1={publisher_sub_id1}&publisher_sub_id2={publisher_sub_id2}&publisher_sub_id3={publisher_sub_id3}&publisher_sub_id4={publisher_sub_id4}&publisher_sub_id5={publisher_sub_id5}&placement={placement}&ua_network={ua_network}&ua_channel={ua_channel}&ua_subpublisher_encrypted={ua_subpublisher_encrypted}&ua_subpublisher_cleartext={ua_subpublisher_cleartext}

Customized (Example)

GET / https://example.com/example?user_id={user_uuid}&sid={sid}&point_amount={coin_amount}&points={currency}&trans_uuid={trans_uuid}&ua_network={ua_network}&ua_channel={ua_channel}&playtime_placement={placement}&custom_id={publisher_sub_id1}

Calculate the SID

sid = sha1(concatenate(trans_uuid, user_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token))

If sdk_app_id and/or device_id are not present in the endpoint URL, they will be excluded from the sid calculation. The sid will then be calculated as follows:

sid = sha1(concatenate(trans_uuid, user_uuid, currency, coin_amount, s2s_token))

Below is an example script that shows how to calculate the sid and compare it to the value in the callback URL sent by adjoe. You would implement some version of this in your backend.

import hashlib
from urllib.parse import urlparse, parse_qs

def calculate_sid(user_uuid, trans_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token):
    data = ''.join([trans_uuid, user_uuid, currency, str(coin_amount), device_id, sdk_app_id, s2s_token])
    hashed_data = hashlib.sha1(data.encode()).hexdigest()
    return hashed_data

def extract_parameters(url):
    parsed_url = urlparse(url)
    query_params = parse_qs(parsed_url.query)
    return query_params

def compare_sids(url, calculated_sid):
    query_params = extract_parameters(url)
    sid_from_url = query_params.get('sid', [None])[0]
    return sid_from_url == calculated_sid

# Example URL
url = "https://s2sexamplerequestendpoint.com/payout?user_uuid=a79d7158-6f9c-4e5b-ae7a-98143c77d396&sid=2477185c00a5b1ac94fdf94798798d5e846d8aee&coin_amount=100&currency=dollars&trans_uuid=e7b1a95f-8c72-4ed8-af69-ecf8d06b1d89&device_id=9a7e993a-80b4-4c3b-832f-97a5f501e2f1&sdk_app_id=com.example.android.gamename&ua_network=tiktok&ua_channel=direct&publisher_sub_id1=RandomString"

# Extract parameters from URL
query_params = extract_parameters(url)
user_uuid = query_params.get('user_uuid', [None])[0]
sid = query_params.get('sid', [None])[0]
trans_uuid = query_params.get('trans_uuid', [None])[0]
currency = query_params.get('currency', [None])[0]
coin_amount = int(query_params.get('coin_amount', [None])[0])
device_id = query_params.get('device_id', [None])[0]
sdk_app_id = query_params.get('sdk_app_id', [None])[0]
s2s_token = " " #the s2s_token will be supplied by your Account Manager.

# Calculate SID
calculated_sid = calculate_sid(user_uuid, trans_uuid, currency, coin_amount, device_id, sdk_app_id, s2s_token)

# Compare SIDs
result = compare_sids(url, calculated_sid)
print("SID Comparison Result:", result)

S2S Security

When we make payout request to publishers, we send an HTTP request from any of the following IP addresses:

3.121.65.44
18.185.166.67
52.29.52.48

To enhance security, use these IP addresses for IP-level blocking on endpoints receiving adjoe's S2S payout requests. Allow only these specific IPs access.

Retry Logic

If we receive a 4xx / 5xx from your endpoint, we have an established retry logic for the failed S2S requests.

If a request fails, we retry after 10 minutes. A second failure prompts a retry in another 10 minutes. Subsequent failures lead to retries every 2 hours from the initial failed attempt. The time windows are additional, so it's roughly 12hrs in total.

Best Practices for Rewarding Users

If you payout with real money, we recommend that you implement KYC processes, reward cooldowns, and individual limits on the amount of rewards the user can get:

• Reward Cooldowns: Temporarily restrict users from receiving additional rewards after receiving one. This helps maintain fairness and prevents exploitation of the rewards system, like receiving rewards too frequently.

• Individual Limits: To prevent abuse of the rewards systems, set daily limits on the amount of rewards a user can earn. For example, you might cap rewards at $50 USD per day.

PlaytimeWeb

Does the the PlaytimeWeb use cookies?

We only keep cookies in the page during the session. It allows us to keep track of the user (like after authentication) and make sure that they get their rewards.

I'm using Flutter or React Native - can I use your Android SDK and iOS solution together?

Yes, you can use the Platform properties provided by the Flutter and React Native libraries to set up the code in a way to conditionally execute certain code blocks based on the platform the app is running on. Since we only have an SDK on Android, you may need to use platform-based imports for RN or add platform-specific dependencies in the pubspec.yaml for Flutter.

Example for React Native:

const showAdjoeOfferwall = async () => {
  if (Platform.OS === 'ios') {
    return navigation.navigate('InAppBrowser', {
      url: `https://{your_company_name}.playtimeweb.com/play?user_id={user_id}&idfa={IDFA}`
    });
  }

  if (adjoeInitialized && Platform.OS === 'android') {
    return await Adjoe.showOfferwall().catch(err => {
      console.error(`Could not show Adjoe offerwall: ${err}`);
    });
  }
};

Using the PlaytimeWeb Catalog

What is the use of the IDFA?

We use the IDFA to identify users and to accurately identify the user for rewarding purposes, ensuring any currency earned via PlaytimeWeb is promptly paid out. We provide the IDFA to MMPs so they can count attribution.

Why does the user need to accept App Tracking?

We have more information about this in our docs. Please refer to them here.

Why does the user need to accept TOS?

We have more information about this in our docs. Please refer to them here. This is what the users sees in the TOS page:

We hereby inform you that adjoe GmbH processes the following personal data within the framework of the use of Playtime:

• Installed apps, IDFA

The data will be connected to your end device via the device ID and sent, encrypted, to our servers. In order for app providers to finance our app suggestions, we must send them the device ID for billing purposes.

Clicking the accept button means that you agree to the data privacy & terms and conditions.

Business

How do I give one of my coworkers access to the dashboard?

You should reach out to your Account Manager. They can provide them with access.

What customization options do you provide for the Playtime Catalog?

Most parts of the PlaytimeWeb Catalog can be customized so that it fits your branding - including images, colors, texts, fonts, and currency. Your Account Manager will reach out to you separately to set up these customizations.

Where can I track KPIs like Revenue or Active User Rates?

These KPIs can be tracked in the Publisher Dashboard. They are also available via API.

Get Further Support

Still need help with something? Have an idea for a Feature Request? Please use this template to reach out to your Account Manager for help.

• Issue Type: [Bug/Feature Request]

• Issue/Feature Description: Provide a detailed description. For feature requests, explain the necessity and potential business impact.

• Reproduction Steps:

• Expected Behavior:

• Actual Behavior:

Please include any relevant logs or screenshots to support your query.

There are 2 parts to implementing and using the Playtime SDK:

Part 1: Intialize the Playtime SDK

Part 2: Launch Playtime

Below is a full example implementation of the Playtime SDK. It uses Jetpack Compose to set up a button that leads the user to the Playtime Offerwall. To run the example:

1. Add the dependency

2. Add your SDK hash

3. If you're using an emulator, add it as a test device.

In the future we will update this page with examples for our other wrappers. Please check back soon.

package com.example.sdk_integration_activity

import android.content.Context
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.size
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import io.adjoe.sdk.Playtime
import io.adjoe.sdk.Playtime.getUserId
import io.adjoe.sdk.PlaytimeException
import io.adjoe.sdk.PlaytimeExtensions
import io.adjoe.sdk.PlaytimeGender
import io.adjoe.sdk.PlaytimeInitialisationListener
import io.adjoe.sdk.PlaytimeNotInitializedException
import io.adjoe.sdk.PlaytimeCatalogListener
import io.adjoe.sdk.PlaytimeParams
import io.adjoe.sdk.PlaytimeUserProfile
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import java.util.Calendar
import java.util.Date

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initPlaytime()
        setupPlaytimeCatalogListener()
    }

// the initPlaytime() function has the playtime params, but if your params have
// changed, or if you don't yet have a param, it is recommended that you take a
// different approach. For example, if you don't get the user ID until after the
// user has signed in. You should then send these values in the OnResume.
private fun initPlaytime()
{
    // pass in the user id. These values should come from your backend.
    // If you don't get the userID until after the sign-in, this value can be passed-in onResume.
    val userId = "f0b9d695-405d-4b13-8a79-5fe21dc901e6"

    // set up the parameters, these values should also come from your backend.
    val playtimeParams = PlaytimeParams.Builder()
        .setUaNetwork("tiktok")
        .setUaChannel("video")
        .setUaSubPublisherCleartext("Example: Game 2")
        .setUaSubPublisherEncrypted("8bb1e7911818be32449f6726ff7ecd102ba1862b")
        .setPlacement("Main Screen")
        .build()

    // these values are additional options that you can pass-in to identify users. These data will be sent back in the S2S URL. Example data below.
    val playtimeExtensions = PlaytimeExtensions.Builder()
        .setSubId1("Target Group 1")
        .setSubId2("Target Group 2")
        .build()

    //Set the options
    val options = Playtime.Options()
        .setUserId(userId)
        .setParams(playtimeParams)
        .setUserProfile(getUserProfile())
        .setExtensions(playtimeExtensions)

    // Initialize the adjoe Playtime SDK, passing in the Playtime Options
    try {
        Playtime.init(this, "your_sdk_hash", options, object : PlaytimeInitialisationListener {
            override fun onInitialisationFinished() {
                // The adjoe Playtime SDK was initialized successfully
                //("initialized successfully")
            }

            override fun onInitialisationError(exception: Exception?) {
                // An error occurred while initializing the Playtime SDK.
                // Note that exception might be null
            }
        })
    } catch (e: PlaytimeNotInitializedException) {
        // Handle initialization exception
    }
    setContent {
        ExampleApp(this)
    }
}

//Get the user profile information. These data should come from your backend. 
    fun getSampleUserGender(): String {
        return "male"
    }

    //Pass in the user's birthday information if it's available
    //and if they've consented to sharing it
    fun getSampleUserBirthday(): Date {
        val birthday = Calendar.getInstance()
        birthday.set(Calendar.YEAR, 1995)
        birthday.set(Calendar.MONTH, Calendar.JANUARY)
        birthday.set(Calendar.DAY_OF_MONTH, 30)

        return birthday.time
    }

    val birthday = getSampleUserBirthday()

    fun getUserProfile(): PlaytimeUserProfile {
        val gender: PlaytimeGender = when (getSampleUserGender()) {
            "male" -> PlaytimeGender.MALE
            "female" -> PlaytimeGender.FEMALE
            else -> PlaytimeGender.UNKNOWN
        }
        return PlaytimeUserProfile(gender, birthday)
    }

//Set up the listener for when the catalog is opened or closed. 
    private fun setupPlaytimeCatalogListener() {
        Playtime.setCatalogListener(object : PlaytimeCatalogListener {
            override fun onCatalogOpened(type: String) {
                Log.d("ADJOE", "Catalog of type '" + type + "' was opened")
            }

            override fun onCatalogClosed(type: String) {
                Log.d("ADJOE", "Catalog of type '" + type + "' was closed")
            }
        })
    }

    //Whenever your app comes back into the foreground,
    //you should init the SDK again and send the updated catalog Params.
    override fun onResume() {
        super.onResume()
        initPlaytime()
    }
}

//Set up the params to send with the teaser. Use this in case you have multiple catalog
// placements in your app and want to evaluate the effectiveness of each.
val teaserPlaytimeParams: PlaytimeParams = PlaytimeParams.Builder()
    .setPlacement("Main Screen")
    .build()

//Set up the additional methods
private suspend fun additionalChecks(context: Context) {
    withContext(Dispatchers.IO) {
        getVersion()
        getVersionName()
        val tosAccepted = hasAcceptedTOS(context)
        val permissionsAccepted = hasAcceptedUsagePermission(context)
        val userIdRetreived = getUserId(context)
    }
}
suspend fun getVersion() {
    val version: Int? = Playtime.getVersion()
    Log.d("ADJOE", "Playtime SDK version is $version")
}

suspend fun getVersionName() {
    val versionName: String? = Playtime.getVersionName()
    Log.d("ADJOE", "Playtime SDK version name is $versionName")
}

suspend fun hasAcceptedTOS(context: Context) {
    val accepted: Boolean? = Playtime.hasAcceptedTOS(context)
    Log.d("ADJOE", "TOS accepted: $accepted")
}

suspend fun hasAcceptedUsagePermission(context: Context) {
    val accepted: Boolean? = Playtime.hasAcceptedUsagePermission(context)
    Log.d("ADJOE", "Usage permission accepted: $accepted")
}

suspend fun getUserId(context: Context) {
    val userId: String? = Playtime.getUserId(context)
    Log.d("ADJOE", "User ID is \"$userId\"")
}

// Set up the teaser event function
private fun sendTeaser(context:Context) {
            Playtime.sendUserEvent(context, Playtime.EVENT_TEASER_SHOWN, null, teaserPlaytimeParams)
        }

@Composable
fun ExampleApp(activity: ComponentActivity) {
    Surface(color = MaterialTheme.colorScheme.background) {
        Column(
            modifier = Modifier.fillMaxSize(),
            verticalArrangement = Arrangement.Center,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            ShowPlaytimeCatalogButton(activity)
        }
    }
}

@Composable
fun ShowPlaytimeCatalogButton(activity: ComponentActivity) {
    val coroutineScope = rememberCoroutineScope()

    Column(
        modifier = Modifier.fillMaxSize(),
        verticalArrangement = Arrangement.Center,
        horizontalAlignment = Alignment.CenterHorizontally
    ) {

        // Button to navigate to the catalog screen
        Button(
            onClick = {
                coroutineScope.launch {
                    try {
                        val catalogCatalogIntent = Playtime.getCatalogIntent(activity)
                        activity.startActivity(playtimeCatalogIntent)
                    } catch(notInitializedException: PlaytimeNotInitializedException) {
                        // Handle not initialized exception
                    } catch(exception: PlaytimeException) {
                        // Handle other exceptions
                    }
                    sendTeaser(context = activity.applicationContext) // send the teaser when the user clicks the Catalog Button. The teaser can also be sent when the user views it.
                    additionalChecks(context = activity.applicationContext) // run the additional checks. 
                }
            },
            modifier = Modifier.size(width = 250.dp, height = 75.dp)
        ) {
            Text("Show Playtime Catalog")
        }
    }
}

@Preview(showBackground = true)
@Composable
fun DefaultPreview() {
    ExampleApp(ComponentActivity())
}

The adjoe Revenue API allows publishers to query user data and generate detailed reports. The required parameter for using this API is the SSP API Token, which you can obtain from your adjoe Account Manager. You can retrieve a report for all apps, as well as for a specific app.

Retrieve a Report for All Apps

GET https://prod.adjoe.zone/v1/ssp-api/<your_token>/aggregation/daily

Required values:

<your_token>: A 32-character hex string provided by your adjoe Account Manager.

You can query data for specific time frames. To query data for a single day, set both start_at and stop_at to that day. Data grouping is customizable; by default, it's grouped by date, country, and platform. For alternative groupings, supply a comma-separated list of fields in the groupBy parameter.

Query Parameters

    {
    "error": "start_at date format is wrong. Please use YYYY-MM-DD"
    }

{"error" : "invalid token"}

Example Request

 curl -X GET \
 'https://prod.adjoe.zone/v1/ssp-api/<your_token>/aggregation/daily?
 start_at=2019-02-18&stop_at=2019-02-18'

Receive a Report a Specific App

GET https://prod.adjoe.zone/v1/ssp-api/<your_token>/aggregation/sdkHash/<sdk_hash>/daily

Required values:

<your_token>: A 32-character hex string token provided by your adjoe Account Manager.

<sdk_hash>: The unique identifier for the SDK, also provided by your adjoe Account Manager.

Data can be queried for specific time ranges. To query for a single day, ensure start_at and stop_at parameters are the same. The default data grouping is by date and app platform. For custom groupings, input a comma-separated list of desired fields in the group_by parameter.

Query Parameters

    {
    "error": "start_at date format is wrong. Please use YYYY-MM-DD"
    }

Example Request:

curl -X GET
https://prod.adjoe.zone/v1/ssp-api/<your_token>/aggregation/sdkHash/<sdk_hash>/daily? start_at=2023-02-18&stop_at=2023-02-18&group_by=platform,country

Schema Definition

Availability

Data is available daily from 2:00 UTC, covering the previous day's activities. To ensure successful API queries, initiate calls after 2:00 UTC.

To make all of the features of the Playtime SDK available, you need to initialize it first. This initialization happens asynchronously in the background, with its completion indicated by a callback method. Make sure to initialize the SDK immediately after the app launches and each time it returns to the foreground.

Initialization

// The initialization will run in the main application process asynchronously in the background and notify you when it is finished by invoking the PlaytimeInitializationListener's onInitialisationFinished or onInitialisationError method.

class MainActivity : AppCompatActivity {
	
    override fun onCreate(savedInstanceState: Bundle?) {
        Playtime.init(this, "sdkHash", options, object: PlaytimeInitialisationListener {
            
            override fun onInitialisationFinished() {
                // the Playtime SDK was initialized successfully
            }
            
            override fun onInitialisationError(exception: Exception?) {
                // an error occurred while initializing the Playtime SDK.
                // note that exception might be null
            }
        })
    }
}

// The initialization will run in the main application process asynchronously in the background and notify you when it is finished by invoking the PlaytimeInitializationListener's onInitialisationFinished or onInitialisationError method.

public class MainActivity extends Activity {

    @Override
    protected void onCreate() {
        super.onCreate();
        Playtime.init(this, "sdkHash", options, new PlaytimeInitialisationListener() {

            @Override
            public void onInitialisationFinished() {
                // the Playtime SDK was initialized successfully
            }

            @Override
            public void onInitialisationError(Exception exception) {
                // an error occurred while initializing the Playtime SDK.
                // note that exception might be null
            }
        });
    }
}

// Should be called during the app start, for example in the App.js's componentDidMount() method

Playtime.init('sdkHash', options).then(() => {
      console.log('Initialized Playtime SDK'); 
    }).catch((err) => {
      console.log('Could not initilize Playtime SDK');
      console.error(err);
    });

// The init method will return a Future<void> which succeeds when the SDK has been initialized successfully and fails with an error when the initialization fails. Make sure to initialize in initState as well as didChangeAppLifecycleState.

import 'package:adjoe/adjoe.dart';
import 'package:adjoe/gender.dart';
import 'package:adjoe/options.dart';
import 'package:adjoe/params.dart';
import 'package:adjoe/user_profile.dart';

void initializePlaytime() {
  Playtime.init(sdkHash, options).then((_) {
    print('Init finished successful');
  }, onError: (err) {
    print('Init failed: $err');
  });
}

using io.adjoe.sdk;

public class Main {

void Start()
{
    Playtime.Init("sdkHash", options, PlaytimeInitialisationSuccess, PlaytimeInitialisationError);
}

public void PlaytimeInitialisationSuccess()
{
    // the Playtime SDK was initialized successfully
}

public void PlaytimeInitialisationError(Exception exception)
{
    // an error occurred while initializing the Playtime SDK.
    // note that exception might be null
}
}

window.PlaytimePlugin.initialize(
  'sdkHash','options',
  function() {
      // the Playtime plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the Playtime plugin.
  },
);

Playtime Options

Pass the following additional options to the Playtime SDK during initialization:

val options = Playtime.Options()
    .setUserId(userId)
    .setParams(playtimeParams);
    .setUserProfile(playtimeUserProfile)
    .setExtensions(playtimeExtensions);

PlaytimeOptions options = new PlaytimeOptions()
    .setUserId(userId)
    .setParams(playtimeParams);
    .setUserProfile(playtimeUserProfile)
    .setExtensions(playtimeExtensions);

Playtime.init('sdkHash', 
    { 
      'userId': "06957070-6579-46cd-9665-d8fe7cd286d5",
      'playtimeParams': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
     'playtimeExtension': {
        'subId1': "RN_subId1",
        'subId2': "RN_subId2",
        'subId3': "RN_subId3",
        'subId4': "RN_subId4",
        'subId5': "RN_subId5"
    }, 
    'playtimeUserProfile': playtimeUserProfile()
    
    }).then(() => {
      console.log('Initialized Playtime SDK');
    })
    .catch((err) => {
      console.log('Could not initilize Playtime SDK');
      console.error(err);
    });

PlaytimeOptions options = new PlaytimeOptions()
  ..userId = 'user_id'
  ..params = (new PlaytimeParams()
    ..uaNetwork = 'The user acquisition network'
    ..uaChannel = 'The user acquisition channel.'
    ..uaSubPublisherCleartext = 'The user acquisition publisher cleartext'
    ..uaSubPublisherEncrypted = 'The user acquisition publisher encrypted'
    ..placement = 'The catalog placement')
  ..userProfile = playtimeUserProfile
  ..extensions = (new PlaytimeExtensions()
    ..subId1 = 'flutter_subId1'
    ..subId2 = 'flutter_subId2'
    ..subId3 = 'flutter_subId3'
    ..subId4 = 'flutter_subId4'  
    ..subId5 = 'flutter_subId5');

PlaytimeOptions options = new PlaytimeOptions()
    .SetUserId(userId)
    .SetPlaytimeParams(playtimeParams)
    .SetPlaytimeUserProfile(playtimeUserProfile)
    .SetPlaytimeExtensions(playtimeExtensions);

// A complete example
window.PlaytimePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'playtime_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'playtime_extension': {
                'subId1': "RN_subId1",
                'subId2': "RN_subId2",
                'subId3': "RN_subId3",
                'subId4': "RN_subId4",
                'subId5': "RN_subId5"
        }, 
        'user_profile': {
                'gender': 'MALE',
                'birthdate': "2023-07-17T22:25:00.000Z"
        }
    },
  function() {
      // the Playtime plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the Playtime plugin.
  },
);

Playtime Parameters

When initializing the SDK, you should include additional User Acquisition and Playtime placement parameters. These parameters allow you to track and analyze Playtime's performance within your app.

You can provide these parameters in any combination, both at initialization and at any point in the app's lifecycle—such as when a user launches the Playtime Catalog interacts with a campaign or requests a payout.

These values must be url-safe as they could potentially be returned as query parameters in the S2S Payout request.

val playtimeParams = PlaytimeParams.Builder()
    .setUaNetwork("network")
    .setUaChannel("channel")
    .setUaSubPublisherCleartext("SubPublisherCleartext")
    .setUaSubPublisherEncrypted("SubPublisherEncrypted")
    .setPlacement("placement")
    .build()
Playtime.setUAParams(context, playtimeParams)

PlaytimeParams playtimeParams = new PlaytimeParams.Builder()
                .setUaNetwork("network")
                .setUaChannel("channel")
                .setUaSubPublisherCleartext("SubPublisherCleartext")
                .setUaSubPublisherEncrypted("SubPublisherEncrypted")
                .setPlacement("placement")
                .build();
Playtime.setUAParams(context, playtimeParams);

playtime.setUAParams({
            'uaNetwork': "RN-uaNetwork",
            'uaChannel': "RN-uaChannel",
            'uaSubPublisherCleartext': "RN-uaSubPublisherCleartext",
            'uaSubPublisherEncrypted': "RN-uaSubPublisherEncrypted",
            'placement': 'RN-placement'
})
.then(() => {
            this.logDialog(`Setting UA prameters were sucessful.`);
})
.catch((err) => {
            this.logDialog(`Setting UA prameters failed.`);
            console.error(err);
});

Playtime.setUAParams(new PlaytimeParams()
        ..uaNetwork = 'uaNetwork'
        ..uaChannel = 'uaChannel'
        ..uaSubPublisherCleartext = 'uaSubPublisherCleartext'
        ..uaSubPublisherEncrypted = 'uaSubPublisherEncrypted'
        ..placement = 'placement');

PlaytimeParams playtimeParams = new PlaytimeParams();
playtimeParams.SetUaNetwork("network")
           .SetUaChannel("Channel")
           .SetUaSubPublisherCleartext("SubPublisherCleartext")
           .SetUaSubPublisherEncrypted("SubPublisherEncrypted")
           .SetPlacement("placement");
Playtime.SetUAParams(playtimeParams);

// A complete example
window.PlaytimePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'playtime_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'playtime_extension': {
                'subId1': "RN_subId1",
                'subId2': "RN_subId2",
                'subId3': "RN_subId3",
                'subId4': "RN_subId4",
                'subId5': "RN_subId5"
        }, 
        'user_profile': {
                'gender': 'male',
                'birthdate': "2023-07-17T22:25:00.000Z"
        }
    },
  function() {
      // the Playtime plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the Playtime plugin.
  },
);

User Profile Information

Our game recommendations are personalized through algorithms that consider users' preferences and gender information. If a user consents to share their gender and/or birthday, you can share this information with adjoe to enhance the customization of game suggestions.

The code below is for demonstration purposes and can be modified to best suit your app's set-up. The important thing is that you get the user's birthday and gender information from your backend and pass in the data to adjoe when initializing.

fun playtimeUserProfile(): PlaytimeUserProfile {
    val gender: PlaytimeGender = when (getUserGender()) {
        "male" -> PlaytimeGender.MALE
        "female" -> PlaytimeGender.FEMALE
        else -> PlaytimeGender.UNKNOWN
    }

// if you don't know the exact birthday, the year is enough
    val birthday: Date = if (isExactBirthdayKnown()) {
        getUserBirthday()
    } else {
        val calendar = Calendar.getInstance()
        calendar.set(Calendar.YEAR, getYearOfBirth())
        calendar.set(Calendar.MONTH, 0)
        calendar.set(Calendar.DAY_OF_MONTH, 0)
        calendar.time
    }

    return PlaytimeUserProfile(gender, birthday)
}

public class UserProfileUtils {

    public static PlaytimeUserProfile playtimeUserProfile() {
        PlaytimeGender gender = getPlaytimeGender(getUserGender());
        Date birthday = getBirthday();
        return new PlaytimeUserProfile(gender, birthday);
    }

    private static PlaytimeGender getPlaytimeGender(String userGender) {
        switch (userGender) {
            case "male":
                return PlaytimeGender.MALE;
            case "female":
                return PlaytimeGender.FEMALE;
            default:
                return PlaytimeGender.UNKNOWN;
        }
    }

    private static String getUserGender() {
        // Implement this method to get the user's gender
        return "male"; // Example placeholder
    }

    private static Date getBirthday() {
        if (isExactBirthdayKnown()) {
            return getUserBirthday();
        } else {
            Calendar calendar = Calendar.getInstance();
            calendar.set(Calendar.YEAR, getYearOfBirth());
            calendar.set(Calendar.MONTH, Calendar.JANUARY);
            calendar.set(Calendar.DAY_OF_MONTH, 1);
            return calendar.getTime();
        }
    }

    private static Date getUserBirthday() {
        // Implement this method to get the user's birthday
        return new Date(); // Example placeholder
    }

    private static boolean isExactBirthdayKnown() {
        // Implement this method to determine if the exact birthday is known
        return true; // Example placeholder
    }

    private static int getYearOfBirth() {
        // Implement this method to get the user's year of birth
        return 1990; // Example placeholder
    }
}

function playtimeUserProfile() {
    const userGender = getUserGender();
    let gender;
    if (userGender === "male") {
        gender = "MALE";
    } else if (userGender === "female") {
        gender = "FEMALE";
    } else {
        gender = "UNKNOWN";
    }

// if you don't know the month or day, you can set them to 01
    let birthday;
    if (isExactBirthdayKnown()) {
        birthday = new Date(getUserBirthday());
    } else {
        const calendar = new Date();
        calendar.setFullYear(getYearOfBirth());
        calendar.setMonth(0);
        calendar.setDate(1);
        birthday = calendar;
    }

    birthday = birthday.toISOString() 
    return { gender, birthday };
}

import 'package:adjoe/user_profile.dart';
import 'package:adjoe/gender.dart';

PlaytimeGender gender;
switch (getUserGender()) {
  case "male":
    gender = PlaytimeGender.MALE;
    break;

  case "female":
    gender = PlaytimeGender.FEMALE;
    break;

  default:
    gender = PlaytimeGender.UNKNOWN;
    break;
}

// set the birthday. If you don't know the user's exact birthday, the year is already enough.
DateTime birthday = getUserBirthday();

PlaytimeUserProfile playtimeUserProfile = PlaytimeUserProfile()
  ..gender = gender
  ..birthday = birthday;

PlaytimeGender gender;
string userGender = GetUserGender();
if (userGender == "male")
    gender = PlaytimeGender.MALE;
else if (userGender == "female")
    gender = PlaytimeGender.FEMALE;
else
    gender = PlaytimeGender.UNKNOWN;

DateTime birthday = new DateTime();
birthday = DateTime.SpecifyKind(birthday, DateTimeKind.Utc);

if (isExactBirthdayKnown())
    {
        birthday = DateTime.Parse(getUserBirthday());
    }
else
    {
        birthday = new DateTime(getYearOfBirth(), 1, 1);
    }

string birthdayIso = birthday.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
PlaytimeUserProfile playtimeUserProfile = new PlaytimeUserProfile(gender, birthdayIso);

//Cordova has a different API that can be used to set the user profile information.

window.PlaytimePlugin.setProfile(
  source,
  gender,
  birthday,
  function() {
    // successfully sent the profile information to adjoe
  },
  function(err) {
    // an error occurred while sending the profile information to adjoe
  },
);

Playtime Extensions

These are optional identifiers used in your backend. They will be provided back in the S2S payout URL.

val playtimeExtensions = PlaytimeExtensions.Builder()
    .setSubId1("subId 1")
    .setSubId2("subId 2")
    .setSubId3("subId 3")
    .setSubId4("subId 4")
    .setSubId5("subId 5")
    .build()

PlaytimeExtensions playtimeExtensions = new PlaytimeExtensions.Builder()
    .setSubId1("subId 1")
    .setSubId2("subId 2")
    .setSubId3("subId 3")
    .setSubId4("subId 4")
    .setSubId5("subId 5")
    .build();

// A complete example
Playtime.init('sdkHash', 
    { 
      'userId': "06957070-6579-46cd-9665-d8fe7cd286d5",
      'applicationProcessName' : "io.adjoe.anyApp",
      'playtimeParams': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'playtimeExtension': {
                'subId1': "RN_subId1",
                'subId2': "RN_subId2",
                'subId3': "RN_subId3",
                'subId4': "RN_subId4",
                'subId5': "RN_subId5"
        }, 
        'playtimeUserProfile': {
                'gender': 'male',
                'birthday': "2023-07-17T22:25:00.000Z"
        }
    
    }).then(() => {
      console.log('Initialized Playtime SDK');
    })
    .catch((err) => {
      console.log('Could not initilize Playtime SDK');
      console.error(err);
    });

PlaytimeOptions options = new PlaytimeOptions()
  ..userId = 'user_id'
  ..applicationProcessName = 'io.adjoe.FlutterTestApp'
  ..params = (new PlaytimeParams()
    ..uaNetwork = 'The user acquisition network'
    ..uaChannel = 'The user acquisition channel.'
    ..uaSubPublisherCleartext = 'The user acquisition publisher cleartext'
    ..uaSubPublisherEncrypted = 'The user acquisition publisher encrypted'
    ..placement = 'The offerwall placement')
  ..userProfile = (new PlaytimeUserProfile()
    ..birthday = birthday
    ..gender = gender)
  ..extensions = (new PlaytimeExtensions()
    ..subId1 = 'flutter_subId1'
    ..subId2 = 'flutter_subId2'
    ..subId3 = 'flutter_subId3'
    ..subId4 = 'flutter_subId4'  
    ..subId5 = 'flutter_subId5');

PlaytimeExtensions playtimeExtensions = new PlaytimeExtensions();
playtimeExtensions.setSubId1("subId 1")
    .setSubId2("subId 2")
    .setSubId3("subId 3")
    .setSubId4("subId 4")
    .setSubId5("subId 5");

// A complete example
window.PlaytimePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'playtime_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'playtime_extension': {
                'subId1': "RN_subId1",
                'subId2': "RN_subId2",
                'subId3': "RN_subId3",
                'subId4': "RN_subId4",
                'subId5': "RN_subId5"
        }, 
        'user_profile': {
                'gender': 'male',
                'birthdate': "2023-07-17T22:25:00.000Z"
        }
    },
  function() {
      // the Playtime plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the Playtime plugin.
  },
);

Checking Initialization

We recommend to verify the SDK is correctly initialized. Each wrapper provides an Playtime.isInitialized method for this purpose. When executed, this method returns true if the SDK is initialized, and false otherwise. Use IsInitialized for debugging or to verify SDK initialization before calling other methods.

The primary function of the Playtime SDK is showing the catalog to the users. The Playtime catalog lists various campaigns that the users can complete to receive a reward in the app's native in-app currency.

Games displayed to users are chosen programmatically based on their preferences and profile, while the specific campaigns available to them depend on the permissions granted or country.

Campaigns

Advertisers define ad formats and target countries through campaigns, which are then featured in the Playtime Catalog. These campaigns are set by advertisers and allow for rewards once the completion of the campaign conditions are verified through the MMP.

Example of a Time-based Campaign

Example of an Event-Based Campaign

Terms of Service

Users need to accept adjoe's Terms of Service (TOS) to use Playtime and access games. Agreeing to the TOS is mandatory before installing any partner apps. After users accept the TOS, we can identify the types of apps/games they have installed, allowing our algorithm to tailor game suggestions on the catalog based on their preferences.

Access to Advertising Info

We also ask the user to accept the App Usage Permissions. This allows us to monitor the time spent in each game or app. Without accepting these permissions, users won't be eligible to participate in Playtime campaigns and will be limited to only Advance or Advance+ campaigns.

How Games Are Matched to Users

The Playtime algorithm prioritizes displaying games to users based on their potential to generate maximum revenue and likelihood of being downloaded.

Add a Teaser Event

When the placement button for Playtime appears, whether clicked or not, please send us the teaser event. This notifies adjoe when and where the placement is shown, which is crucial for tracking user engagement and enhancing the user experience.

Use playtimeParams to pass in the placement information, i.e., where in the app the button was shown - for example: "Main Page".

try {
    Playtime.sendUserEvent(context, Playtime.EVENT_TEASER_SHOWN, null, playtimeParams)
} 
catch (e: PlaytimeNotInitializedException) {
    // you have to initialize the Playtime SDK
}

try {
    Playtime.sendUserEvent(context, Playtime.EVENT_TEASER_SHOWN, null, playtimeParams);
}
catch (PlaytimeNotInitializedException e) {
    // you have to initialize the Playtime SDK
}

Playtime.sendEvent(Playtime.EVENT_TEASER_SHOWN, null, {'<playtimeParams>'});

Playtime.sendTeaserShownEvent(params);

Playtime.sendEvent(Playtime.EVENT_TEASER_SHOWN, null, playtimeParams);

function() {
    // show teaser button
        window.PlaytimePlugin.sendUserEvent(window.PlaytimePlugin.EVENT_TEASER_SHOWN, '<subId1>', '<subId2>');
    },
function() {
        //can't show the catalog 
    }

Launch the Playtime Catalog

We recommend triggering the catalog via a button or UI element (within the SDK it is housed in a separate activity). Rather than launching the activity directly, we provide an Intent for you to initiate it, enabling, for example, transition animations for a smoother user experience Use the code below to display the adjoe Playtime Offerwall. It is recommended to send any updated PlaytimeParams when launching the Playtime Catalog.

try {
    val playtimeParams = PlaytimeParams.Builder()
        .setUaNetwork("network")
        .setUaChannel("channel")
        .setUaSubPublisherCleartext("SubPublisherCleartext")
        .setUaSubPublisherEncrypted("SubPublisherEncrypted")
        .setPlacement("placement")
        .build()
    val playtimeCatalogIntent = Playtime.getCatalogIntent(context, playtimeParams)
    context.startActivity(playtimeCatalogIntent)
} 
    catch(notInitializedException: PlaytimeNotInitializedException) {
    // you have not initialized the Playtime SDK
} 
    catch(exception: PlaytimeException) {
    // the catalog cannot be displayed for some other reason
}

try {
    PlaytimeParams playtimeParams = new PlaytimeParams.Builder()
            .setUaNetwork("network")
            .setUaChannel("channel")
            .setUaSubPublisherCleartext("SubPublisherCleartext")
            .setUaSubPublisherEncrypted("SubPublisherEncrypted")
            .setPlacement("placement")
            .build();
    Intent playtimeCatalogIntent = Playtime.getCatalogIntent(context, playtimeParams);
    context.startActivity(playtimeCatalogIntent);
} 
        catch (PlaytimeNotInitializedException notInitializedException) {
    // you have not initialized the Playtime SDK
} 
        catch (PlaytimeException exception) {
    // the catalog cannot be displayed for some other reason
}

Playtime.showCatalog({
	'uaNetwork': "uaNetwork_value",
	'uaChannel': "uaChannel_value",
	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
	'placement': 'placement_value'
})
    .then(() => {
        console.log('Now showing Playtime offerwall');
    })
    .catch((err) => {
        console.log('Could not show Playtime offerwall');
        console.error(err);
    });

PlaytimeParams params = new PlaytimeParams()
    ..uaNetwork = 'network'
    ..uaChannel = 'channel'
    ..uaSubPublisherCleartext = 'cleartext'
    ..haSubPublisherEncrypted = 'encrypted'
    ..placement = 'placement';
Playtime.showPlaytime(params);

PlaytimeParams playtimeParams = new PlaytimeParams();
playtimeParams.SetUaNetwork("network")
    .SetUaChannel("Channel")
    .SetUaSubPublisherCleartext("SubPublisherCleartext")
    .SetUaSubPublisherEncrypted("SubPublisherEncrypted")
    .SetPlacement("placement");
Playtime.ShowCatalog(playtimeParams)

window.PlaytimePlugin.showCatalog(
  function() {
    // the catalog was displayed to the user
  },
  function(err) {
    // the catalog cannot be displayed
  },
);

//You can pass two optional Sub-IDs when you launch Playtime, which will be logged every time a user views or clicks a campaign: 
window.PlaytimePlugin.showCatalogWithSubIDs('<subId1>', '<subId2>', success, error).

Set Up a Listener (Native)

You can set up a listener to be notified when the Playtime Catalog is opened or closed, with the event type always being catalog. To remove the listener, simply call Playtime.removeCatalogListener().

Playtime.setCatalogListener(object:PlaytimeCatalogListener() {
  fun onCatalogOpened(type:String) {
    Log.d(TAG, "Catalog of type '" + type + "' was opened")
  }
  fun onCatalogClosed(type:String) {
    Log.d(TAG, "Catalog of type '" + type + "' was closed")
  }
})

Playtime.setCatalogListener(new PlaytimeCatalogListener() {

    @Override
    public void onCatalogOpened(String type) {
        Log.d(TAG, "Catalog of type '" + type + "' was opened");
    }

    @Override
    public void onCatalogClosed(String type) {
        Log.d(TAG, "Catalog of type '" + type + "' was closed");
    }
});

Example: Playtime Catalog & My Games

Additional Useful Methods

The adjoe User Ad Data Report API allows publishers to request user data reports. The required parameter for using this API is the SSP API Token, which you can obtain from your adjoe Account Manager.

There are two steps to using the User Ad Data Report API:

1. Get the Report URL: Use your SSP API Token and Date to request a URL.

2. Download the Report: Access the URL to obtain your report.

Step 1: Obtain the Report URL

GET https://prod.adjoe.zone/v1/ssp-api/<your_token>/user-ad-data-report/app/<your_app_id>?date=[YYYY-MM-DD]

Required values:

<your_token> - 32-character hex string provided by the adjoe Account Manager.

<your_app_id> - Android package name or iOS Appstore ID. Example: com.king.candycrush

Query Parameters

Example Request

curl -X GET
'https://prod.adjoe.zone/v1/ssp-api/acbd18db4cc2f85cedef654fccc4a4d8/user-ad-data-report/app/com.king.candycrush4?date=2024-02-01'

Step 2: Obtain the Report

After obtaining the URL, download the report in CSV format. A successful download will prompt an HTTP 200: OK status, along with the CSV file. An empty file indicates no data is available yet.

Example Report 1:

"2024-02-01","6f2fb2d3def4f99053edab239195f146","android","com.king.candycrush4","DE","3d497f11-4e04-469c-821a-1f57429efb1a","0ca80a38-bb08-4365-8887-5014bf25373b","1ba8e52e-a967-422c-b67e-528511b9780b","Placement one","Home Screen",0.000,0.000,7

Example Report 2:

"2024-02-01","9e304d4e8df1b74cfa009913198428ab","ios","1225867923","DE","3d49"

Schema Definition

Availability

Data is available daily from 2:00 UTC, covering the previous day's activities. To ensure successful API queries, initiate calls after 2:00 UTC. Access to reports is granted after your Account Manager has authorized them. For example, if your report is enabled on 2024-01-01, you can access it from 2:00 UTC on 2024-01-02. Note: Reports for periods before the enablement date, such as before 2024-01-01, are not accessible.

The primary function of PlaytimeWeb is showing the catalog to the users. The Playtime lists various campaigns that the users can complete to receive a reward in your app's native in-app currency.

Games displayed to users are chosen programmatically based on their preferences and profile, while the specific campaigns available to them depend on the permissions granted or country.

Campaigns

Advertisers define ad formats and target countries through campaigns, which are then featured in the Playtime Catalog. These campaigns are set by advertisers and allow for rewards once the completion of the campaign conditions are verified through the . PlaytimeWeb only supports "event-based" campaigns. Meaning that the user will get rewarded for completing different levels or tasks.

Example of an Event-Based Campaign

Terms of Service

Users need to accept adjoe's Terms of Service (TOS) to use Playtime and access games. Agreeing to the TOS is mandatory before installing any partner apps.

iCloud Relay

How Games Are Matched to Users

The Playtime algorithm prioritizes displaying games to users based on their potential to generate maximum revenue and likelihood of being downloaded.

Example: Playtime Catalog & My Games

3.0.0

Published: November 11th, 2024

Breaking Changes 🚨

• Adjoe has been renamed to Playtime.

• Offerwall has been renamed to Catalog.

For React Native Only:

• user-id has been renamed to userId

The following APIs have been impacted by these changes. Please update your code so that the correct APIs are used.

Bug fixes 🪲

• Fix a crash regarding loading resources in WebView

• Remove additional = in playtime notification for certain translations

• Fix not opening installed campaign apps for Android >= 13

• Stop using setDataDirectorySuffix of WebView

• Fix crash related to the visibility of AdjoeActivity

Features and Improvements ✨

• Add API Reference

• Support customisable texts in reward notifications

• Automatically redirect users to the app after accepting the Android usage permissions

• Open the usage permission screen within the app rather than the Android Settings

• Add type definitions in React Native Wrapper

• Add enhanced detection of suspicious users

• Improve error handling and performance through removal of unused internal classes

• Improve security of WebView settings

Migrate to 3.0.0

1. Update method and class names

• Update usages of Adjoe to Playtime.

• Update usages of Offerwall to Catalog.

For React Native Only:

• Update usages of user-id to userId

2. Remove usages of the following API:

• setProfile - Instead you should use setUserProfile with PlaytimeOptions during the init.

• canShowOfferwall / canShowCatalog

2.2.2

Published: 17 July 2024

Bug fixes 🪲

• Fix ANR related to protection library

2.2.1

Published: 24 May 2024

Bug fixes 🪲

• Fix "webpage not available" error which occurred occasionally when returning back to Playtime from the Play Store

• Fix Proguard issue that occurred while building a release version of the APK

• Improve the SDK's “notification” logic.

• Fix exception caused by running multiple processes

Features and Improvements ✨

• Deprecate canShowOfferwall API

• Deprecate setProfile API

• Improve Korean translations

• Add enhanced detection of suspicious users

2.2.0

Published: 21 March 2024

Bug fixes 🪲

• Improve usage permission handling on Android 13+

Features and Improvements ✨

• Add enhanced detection of suspicious users

• Add cash currency support in reward notifications

2.1.1

Published at: 19 December 2023

• Bug fixes

• Enhance Fraud detection

• Translation fixes for the notifications

• Fix for users that were not getting rewarded for the installed apps after they updated an SDK.

• Supporting all React Native versions.

2.1.0

Published at: 28 July 2023

• Bug fixes

• Enhance Fraud detection

• Usage collection enhancement

• Fixed an inconsistency in the External User ID

• You can now use the Adjoe.setUAParams(adjoeParams : AdjoeParams) to add additional parameters.

• Added translation for additional 7 languages ( in, it, ja, ko, pl, pt and tr) in addition to en, de, es, fr

• consistent update cross all wrappers to mark this update as the new base line

2.0.7

Published at: 16 Mar 2023

• Android 13 support

• Depreciation of safetynet and replacing it with play integrity

• New fraud update [VPN-detection]

2.0.5

Published at: 11 Nov 2022

• Fix issues with notification.

• Enhancements and improvements of workmanager and threading.

• Bug fixes.

2.0.4

Published at: 14 Sep 2022

• Fix issues with rewards.

• Allow multiple init without throwing Already Initialised Exception.

• Error visibility enhancement.

• Bug fixes.

2.0.2

Published at: 11 Mar 2022

• Migrate SDK to Androidx.

• Add full support to android12.

• Adding android:export in Manifest.

• Update workManager library to 2.7.1.

• Add flag IMMUTABLE and MUTABLE to pendingIntent.

• Bug fixes.

• Further enhancement.

1.5.1

Published at: 8 Oct 2021

• Further enhancements on crash reports

• Bugfixes

1.5.0

Published at: 14.09.2021

• Additional scenarios to display Advance campaigns.

• Enhance crash reports.

• Fix Network issues.

• Bugfixes.

1.4.15

Published at: 08.06.2021

• Added App Info Fields to Campaigns.

• Added Support for Advance.

• Usage/Reward Enhancements.

• Bugfixes.

1.4.14

Published at: 24.03.2021

• Made the SDK lighter on permissions.

1.4.13.1

Published at: 10.03.2021

• Resolved potential compatibility issues surrounding the WorkManager library.

1.4.13

Published at: 03.03.2021

• Full support for android 11 on targetSDKVersion 30.

• Improved the Toast Notification to give users immediate feedback.

• Improved the usage collection reliability.

• Changed Sub-ID handling with AdjoeParams object to provide further context on the users (such as User Acquisition data and the Playtime placement).

1.4.12

Published at: 28.01.2021

• Improved initialization speed.

• Improved onboarding user flow on Android 10+.

• Bugfix for potential crashes.

1.4.11

Published at: 30.11.2020

• Bugfixing for calling the init method outside the main process.

• Bugfix for accepting the TOS without a network connection.

1.4.10

Published at: 04.11.2020

• Bugfixes for building on Windows.

1.4.9

Published at 29.10.2020

• Bugfixes for apps using minified R8/ProGuard builds.

1.4.8

Published at 07.10.2020

• Bugfixes.

1.4.7

Published at 25.09.2020

• Kotlin: Fixed Adjoe.Options in Kotlin.

• Unity: Added inline documentation.

• Unity: The methods now output logs when called inside the Unity Editor.

1.4.6

Published at: 16.09.2020‌