Once a user meets the campaign 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

For security measures, a request signature is necessary to verify the authenticity of the request. It's important to calculate the sid parameter in your backend and compare it with the parameter received in the callback URL. The sid is generated as an SHA1 hash using the required query parameters and the encoding is hexadecimal. Your Account Manager will provide you with the necessary parameter, the s2s_token. The general format for this is as follows - no other parameters are included in the calculation:

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:

• KYC or Know Your Customer: This verification process, used by businesses and financial institutions, confirms the identity of your users to prevent fraud. It involves collecting and verifying identification documents, such as government-issued IDs or proof of address, ensuring that users are who they claim to be.

• 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?

Why does the user need to accept App Tracking?

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, 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.

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?

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.

The primary function of PlaytimeWeb is showing the catalog to the users. The Playtime catalog 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 MMP. 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

For iOS users Apple provides an opportunity to use the iCloud Private Relay service, which can be enabled in the device settings. If the user has it enabled, then we cannot track the user’s real IP, since all the requests would be proxied via Apple servers. This can have an impact on our ability to reward users for playing games. In cases where iCloud Private Relay enabled, users would see the following messages asking them to disable it. We will not permit users to play games without disabling this feature.

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

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 eCPM and engagement metrics in return. To learn more about how adjoe can boost your app's monetization, engagement, and retention, click here.

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.

Additionally, you can include extra parameters in the URL, and these values will be sent back to you through the Server-to-Server payout URL

Supported URL Parameters

Accept Tracking

While the IDFA parameter is not required, we recommend including it. This means you should trigger the App Tracking Transparency popup so the user can "Allow" tracking. When a user selects "Play Now" in the Playtime Offerwall, we use a pop-up to remind them to allow 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.