Initialize the Playtime SDK

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.

Best practices for the SDK initialization:

• Initialize early: Initialize the SDK as soon as possible after your app starts. This ensures all Playtime SDK features are ready for use right away.

• Initialize after your app authentication: Once a user signs up or logs in, initialize the SDK again with the latest user details. This updates the userID within the SDK.

• Initialize regularly: For the best user experience, call the init method every time your app comes into the foreground. Doing so will not affect your app's performance.

• Initialization triggers: Call the init method at the app start and resume (when the app comes back into the foreground).

Initialization

Kotlin

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

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

Java

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

public class MainActivity extends Activity {

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

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

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

React Native

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

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

Flutter

// 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 initializeAdjoe() {
  Adjoe.init(sdkHash, options).then((_) {
    print('Init finished successful');
  }, onError: (err) {
    print('Init failed: $err');
  });
}

Unity

using io.adjoe.sdk;

public class Main {

void Start()
{
    Adjoe.Init("sdkHash", options, AdjoeInitialisationSuccess, AdjoeInitialisationError);
}

public void AdjoeInitialisationSuccess()
{
    // the adjoe SDK was initialized successfully
}

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

Cordova

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

Important: Initialization must happen on the main thread since it's a UI-related action. Calling any of the init methods off the main thread could lead to app disruptions.

adjoe Options

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

Parameter	Type	Explanation
User ID	String	A custom identifier you can assign to each user. If you haven't set one, the Playtime SDK generates it automatically. It is accessible through Adjoe.getUserId(Context). This ID is necessary for S2S payouts, thus required. Ensure this value is url-safe and that the value is never empty.
Parameters	Object	Values for the User Acquisition and Playtime placement information. These values must be url-safe. More on this below.
User Profile	Object	Birthday and gender data of the app users. This data is used by adjoe to provide the best campaigns for the user. More on this below.
Extensions	Object	These are optional identifiers used in your backend. They will be provided back in the S2S payout.

Kotlin

val options = Adjoe.Options()
    .setUserId(userId)
    .setParams(adjoeParams);
    .setUserProfile(adjoeUserProfile)
    .setExtensions(adjoeExtensions);

Java

Adjoe.Options options = new Adjoe.Options()
    .setUserId(userId)
    .setParams(adjoeParams);
    .setUserProfile(adjoeUserProfile)
    .setExtensions(adjoeExtensions);

React Native

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

Flutter

AdjoeOptions options = new AdjoeOptions()
  ..userId = 'user_id'
  ..params = (new AdjoeParams()
    ..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 = adjoeUserProfile
  ..extensions = (new AdjoeExtensions()
    ..subId1 = 'flutter_subId1'
    ..subId2 = 'flutter_subId2'
    ..subId3 = 'flutter_subId3'
    ..subId4 = 'flutter_subId4'  
    ..subId5 = 'flutter_subId5');

Unity

AdjoeOptions options = new AdjoeOptions()
    .SetUserId(userId)
    .SetAdjoeParams(adjoeParams)
    .SetAdjoeUserProfile(adjoeUserProfile)
    .SetAdjoeExtensions(adjoeExtensions);

Cordova

// A complete example
window.AdjoePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'adjoe_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'adjoe_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 adjoe plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the adjoe plugin.
  },
);

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

To make the most of the Playtime SDK, to maximize your revenue and provide the best user experience, use all of these parameters for data-driven optimizations. For instance, you can monitor the performance of different Playtime button placements or determine the effectiveness of different UA sources.

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

Parameter	Type	Explanation
UA Network	String	User Acquisition Network. The network through which the user was acquired, e.g., Adwords, Facebook, or Organic.
UA Channel	String	User Acquisition Channel. The channel within the network from which the user was acquired, e.g. incentivized or video campaigns.
User Acquisition Sub Publisher Cleartext	String	The cleartext package name of the sub-publisher's app ID within the network from which the user was acquired, e.g., com.domain.appName.
User Acquisition Sub Publisher Encrypted	String	The encrypted package name or app ID of the sub-publisher's app from the network where the user was acquired.
Placement	String	The placement of the Playtime Offerwall inside your app, e.g., "Main Screen", "Shop", "Interstitial", "More Diamonds Screen", etc.

Kotlin

val adjoeParams = AdjoeParams.Builder()
    .setUaNetwork("network")
    .setUaChannel("channel")
    .setUaSubPublisherCleartext("SubPublisherCleartext")
    .setUaSubPublisherEncrypted("SubPublisherEncrypted")
    .setPlacement("placement")
    .build()
Adjoe.setUAParams(context, adjoeParams)

Java

AdjoeParams adjoeParams = new AdjoeParams.Builder()
                .setUaNetwork("network")
                .setUaChannel("channel")
                .setUaSubPublisherCleartext("SubPublisherCleartext")
                .setUaSubPublisherEncrypted("SubPublisherEncrypted")
                .setPlacement("placement")
                .build();
Adjoe.setUAParams(context, adjoeParams);

React Native

adjoe.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);
});

Flutter

Adjoe.setUAParams(new AdjoeParams()
        ..uaNetwork = 'uaNetwork'
        ..uaChannel = 'uaChannel'
        ..uaSubPublisherCleartext = 'uaSubPublisherCleartext'
        ..uaSubPublisherEncrypted = 'uaSubPublisherEncrypted'
        ..placement = 'placement');

Unity

AdjoeParams adjoeParams = new AdjoeParams();
adjoeParams.SetUaNetwork("network")
           .SetUaChannel("Channel")
           .SetUaSubPublisherCleartext("SubPublisherCleartext")
           .SetUaSubPublisherEncrypted("SubPublisherEncrypted")
           .SetPlacement("placement");
Adjoe.SetUAParams(adjoeParams);

Cordova

// A complete example
window.AdjoePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'adjoe_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'adjoe_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 adjoe plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the adjoe 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.

The birthday data should be in ISO format. If your data doesn't already look like that, please make sure to format it so that it is. Example: 2023-07-17T22:25:00.000Z

Kotlin

fun adjoeUserProfile(): AdjoeUserProfile {
    val gender: AdjoeGender = when (getUserGender()) {
        "male" -> AdjoeGender.MALE
        "female" -> AdjoeGender.FEMALE
        else -> AdjoeGender.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 AdjoeUserProfile(gender, birthday)
}

Java

public class UserProfileUtils {

    public static AdjoeUserProfile adjoeUserProfile() {
        AdjoeGender gender = getAdjoeGender(getUserGender());
        Date birthday = getBirthday();
        return new AdjoeUserProfile(gender, birthday);
    }

    private static AdjoeGender getAdjoeGender(String userGender) {
        switch (userGender) {
            case "male":
                return AdjoeGender.MALE;
            case "female":
                return AdjoeGender.FEMALE;
            default:
                return AdjoeGender.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
    }
}

React Native

function adjoeUserProfile() {
    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 };
}

Flutter

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

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

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

  default:
    gender = AdjoeGender.UNKNOWN;
    break;
}

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

AdjoeUserProfile adjoeUserProfile = AdjoeUserProfile()
  ..gender = gender
  ..birthday = birthday;

Unity

AdjoeGender gender;
string userGender = GetUserGender();
if (userGender == "male")
    gender = AdjoeGender.MALE;
else if (userGender == "female")
    gender = AdjoeGender.FEMALE;
else
    gender = AdjoeGender.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");
AdjoeUserProfile adjoeUserProfile = new AdjoeUserProfile(gender, birthdayIso);

Cordova

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

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

adjoe Extensions

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

Kotlin

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

Java

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

React Native

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

Flutter

AdjoeOptions options = new AdjoeOptions()
  ..userId = 'user_id'
  ..applicationProcessName = 'io.adjoe.FlutterTestApp'
  ..params = (new AdjoeParams()
    ..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 AdjoeUserProfile()
    ..birthday = birthday
    ..gender = gender)
  ..extensions = (new AdjoeExtensions()
    ..subId1 = 'flutter_subId1'
    ..subId2 = 'flutter_subId2'
    ..subId3 = 'flutter_subId3'
    ..subId4 = 'flutter_subId4'  
    ..subId5 = 'flutter_subId5');

Unity

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

Cordova

// A complete example
window.AdjoePlugin.initialize(
  'sdkHash',
  { 
        'user_id': getUserId(),
        'adjoe_params': {
                'uaNetwork': "uaNetwork_value",
          	'uaChannel': "uaChannel_value",
          	'uaSubPublisherCleartext': "uaSubPublisherCleartext_value",
          	'uaSubPublisherEncrypted': "uaSubPublisherEncrypted_value",
          	'placement': 'placement_value'
        }, 
        'adjoe_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 adjoe plugin was initialized successfully
  },
  function(err) {
      // an error occurred while initializing the adjoe plugin.
  },
);

Checking Initialization

We recommend to verify the SDK is correctly initialized. Each wrapper provides an Adjoe.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.

Important: Do not call Adjoe.init based on the result of isInitialized.The SDK already performs its own initialization checks. Doing so again may degrade the user experience.