> For the complete documentation index, see [llms.txt](https://sdk-doc.tyrads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdk-doc.tyrads.com/android-beta/initialization.md).

# Initialization

{% hint style="warning" %}

#### Initialize After Media Source or MMP Initialization

Please initialize our SDK only after the media source or MMP data is initialized. This ensures that the media source data is sent correctly and prevents passing empty values.
{% endhint %}

Integrating the Tyrads offerwall functionality into your application is a straightforward process that involves a few key steps. By following these integration steps, you can seamlessly incorporate the offerwall feature, enhancing user engagement and potentially generating revenue for your application.

### 1. Initialization

{% hint style="success" %}

### SDK Initialization best practices:

* **Initiate early:** It's advisable to initialize the SDK promptly after your app launches to ensure that all Tyr SDK functionalities are accessible when needed.
* **Initiate post-app authentication:** Re-initiate the SDK with current user details immediately after your user signs up or signs in to the app to update the `userId`.
* **Initiate periodically:** To optimize user experience, we strongly suggest invoking this method each time your app is brought to the forefront. This shouldn't impact your app's performance noticeably.
  {% endhint %}

This step initializes the Tyrads SDK within your application. You need to provide the API key and API secret obtained from the Tyrads platform. This allows your app to communicate securely with Tyrads' servers.

| Parameter         | Type                    | Required | Description                                                                                                                     |
| ----------------- | ----------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------- |
| `context`         | `ApplicationContext`    |  **Yes** | The application or activity context.                                                                                            |
| `apiKey`          | `String`                |  **Yes** | Your unique publisher identifier obtained from the Tyrads Dashboard.                                                            |
| `apiSecret`       | `String`                |  **Yes** | Your publisher secret key used for secure server communication.                                                                 |
| `encKey`          | `String`                |    No    | **Encryption Key**: If provided, the SDK encrypts sensitive data during transmission. Recommended for high-security apps.       |
| `placementId`     | `String`                |    No    | Used to differentiate between different  coins and use as per your selection within your app.                                   |
| `userInfo`        | `TyradsUserInfo`        |    No    | Metadata about the user (email, phone, user group) used for segmenting and personalizing offers.                                |
| `mediaSourceInfo` | `TyradsMediaSourceInfo` |    No    | **Attribution Data**: Details about where the user came from (e.g., Facebook, Organic). Helps in tracking campaign performance. |
| `config`          | `TyradsConfig`          |    No    | Android Only: settings for Android behavior, such as `skipInitialPages` to bypass privacy/permission screens.                   |
| `launchMode`      | `TyradsLaunchMode`      |    No    | Internal configuration for how the offerwall container is launched.                                                             |

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
CoroutineScope(Dispatchers.Main).launch {
    try {
        Tyrads.getInstance().init(
            context = applicationContext,
            apiKey = "YOUR_API_KEY",
            apiSecret = "YOUR_API_SECRET",
            encryptionKey = "YOUR_ENCRYPTION_KEY", // Optional
            engagementId = "YOUR_ENGAGEMENT_ID",   // Optional
            placementId = "YOUR_PLACEMENT_ID",     // Optional
            config = TyradsConfig(
                skipInitialPages = true // Bypasses consent screens
            ),
            debugMode = false // Set to true to view SDK console logs
        )
        // SDK initialized successfully
    } catch (e: Exception) {
        // Handle initialization failure
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
import com.tyrads.sdk.Tyrads;
import com.tyrads.sdk.TyradsCallback;
import com.tyrads.sdk.acmo.modules.input_models.TyradsConfig;

Tyrads.getInstance().init(
    context,
    "YOUR_API_KEY",
    "YOUR_API_SECRET",
    "YOUR_ENCRYPTION_KEY", // Optional (pass null if not needed)
    "YOUR_ENGAGEMENT_ID",   // Optional (pass null if not needed)
    "YOUR_PLACEMENT_ID",     // Optional (pass null if not needed)
    new TyradsConfig(true),  // skipInitialPages = true
    false,                   // debugMode = false
    new TyradsCallback() {
        @Override
        public void onSuccess() {
            // SDK initialized successfully
        }

        @Override
        public void onFailure(String error) {
            // Handle initialization failure
        }
    }
);
```

{% endtab %}
{% endtabs %}

`encryptionKey`: This would be used for encrypting data transmitted from the SDK. If not provided, data will be transmitted plain form.

`engagementId`: Optional engagement identifier to associate SDK activity with specific user engagements or campaigns.

`placementId`: Used to differentiate between different  coins and use as per your selection within your app.

`config`: (New) Configuration object (`TyradsConfig`) to customize SDK behavior. For example, `skipInitialPages` a Boolean (true or false) can be set dynamically. The `skipInitialPages` option in the `TyradsConfig` allows your app to bypass certain introductory pages during SDK initialization. When set to `true`, the SDK will **skip the Privacy and Terms & Conditions page as well as the Usage Permission page**, allowing users to enter directly into the main app experience without having to manually navigate through these consent or informational screens.

### 1.1 Advanced Practices for initialization for personalized rewards

{% hint style="warning" %}
To maximize the value to the user sending us more data about the user and where they came from allow us to customize the reward experience. This can be used to provide feedback of quality of users aswell as customize the earnings journey of different segments of users. 
{% endhint %}

To maximize the value of our Tyr SDK please follow the advanced options for initialization. This will allow us to personalize the rewards for the user event further and maximize the earnings for you as publisher. 

> \[!NOTE] Unassigned fields in `TyradsMediaSourceInfo` or `TyradsUserInfo` default to `null` automatically. Omit fields you do not require; there is no need to set them manually.

**Attributes Table**

| Data Model                | Parameter           | Type    | Description / Formatting                                                          |
| ------------------------- | ------------------- | ------- | --------------------------------------------------------------------------------- |
| **TyradsUserInfo**        | `email`             | String  | User's email address                                                              |
|                           | `phoneNumber`       | String  | User's phone number. Prefix `+` must be replaced with `00` (e.g. `0015555551234`) |
|                           | `userGroup`         | String  | Segment identifier (e.g. `"High purchase user"`)                                  |
|                           | `age`               | Int     | User's age                                                                        |
|                           | `gender`            | Int     | User's gender                                                                     |
| **TyradsMediaSourceInfo** | `mediaSourceName`   | String  | Platform of acquisition (e.g. `"Facebook"`, `"Google"`)                           |
|                           | `mediaCampaignName` | String  | Associated ad campaign name                                                       |
|                           | `mediaSourceId`     | String  | Unique ID representing the media source                                           |
|                           | `mediaSubSourceId`  | String  | Sub-source ID                                                                     |
|                           | `incentivized`      | Boolean | If the acquisition was via incentivized networks                                  |
|                           | `mediaAdsetName`    | String  | Acquisition ad set name                                                           |
|                           | `mediaAdsetId`      | String  | Acquisition ad set ID                                                             |
|                           | `mediaCreativeName` | String  | Acquisition ad creative asset name                                                |
|                           | `mediaCreativeId`   | String  | Acquisition ad creative asset ID                                                  |
|                           | `sub1` to `sub5`    | String  | Custom parameters for publisher tracking                                          |

**⚠️ Rule for Metadata Binding**

Always call `setMediaSourceInfo` and `setUserInfo` **immediately prior** to calling `init` or `loginUser` to guarantee that sessions are tracked with valid acquisition data.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
import com.tyrads.sdk.Tyrads
import com.tyrads.sdk.TyradsUserInfo
import com.tyrads.sdk.TyradsMediaSourceInfo
import com.tyrads.sdk.acmo.modules.input_models.TyradsConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

CoroutineScope(Dispatchers.Main).launch {
    // 1. Prepare User and Media Source data
    val userInfo = TyradsUserInfo(
        email = "example@tyrads.com",
        phoneNumber = "87653211223",
        userGroup = "High purchase user"
    )
    val mediaSourceInfo = TyradsMediaSourceInfo(
        mediaSourceName = "Facebook",
        mediaCampaignName = "Summer Sale",
        mediaSourceId = "123",
        mediaSubSourceId = "A1",
        incentivized = true,
        mediaAdsetName = "AdSet1",
        mediaAdsetId = "AS123",
        mediaCreativeName = "CreativeBanner",
        mediaCreativeId = "CB123",
        sub1 = "user123",
        sub2 = "app_launch"
    )

    // 2. Set details prior to init
    Tyrads.getInstance().setMediaSourceInfo(mediaSourceInfo)
    Tyrads.getInstance().setUserInfo(userInfo)

    // 3. Initialize SDK
    Tyrads.getInstance().init(
        context = applicationContext,
        apiKey = "YOUR_API_KEY",
        apiSecret = "YOUR_API_SECRET",
        encryptionKey = "YOUR_ENCRYPTION_KEY",
        engagementId = "YOUR_ENGAGEMENT_ID",
        config = TyradsConfig(skipInitialPages = true)
    )
}
```

{% endtab %}

{% tab title="Java" %}

```java
import com.tyrads.sdk.Tyrads;
import com.tyrads.sdk.TyradsCallback;
import com.tyrads.sdk.TyradsUserInfo;
import com.tyrads.sdk.TyradsMediaSourceInfo;
import com.tyrads.sdk.acmo.modules.input_models.TyradsConfig;

// 1. Prepare structures
TyradsUserInfo userInfo = new TyradsUserInfo(
    "example@tyrads.com",
    "987653211223",
    "High purchase user",
    null, // age
    null  // gender
);

TyradsMediaSourceInfo mediaSourceInfo = new TyradsMediaSourceInfo(
    "Facebook",
    "Summer Sale",
    "123",
    "A1",
    true,
    "AdSet1",
    "AS123",
    "CreativeBanner",
    "CB123",
    "user123",
    "app_launch",
    null, // sub3
    null, // sub4
    null  // sub5
);

// 2. Set details prior to init
Tyrads.getInstance().setMediaSourceInfo(mediaSourceInfo);
Tyrads.getInstance().setUserInfo(userInfo);

// 3. Initialize SDK
Tyrads.getInstance().init(
    context,
    "YOUR_API_KEY",
    "YOUR_API_SECRET",
    "YOUR_ENCRYPTION_KEY",
    "YOUR_ENGAGEMENT_ID",
    null, // placementId
    new TyradsConfig(true),
    false,
    new TyradsCallback() {
        @Override
        public void onSuccess() {
            // SDK initialized
        }

        @Override
        public void onFailure(String error) {
            // Init failed
        }
    }
);
```

{% endtab %}
{% endtabs %}

[Sending Media Source Data](/getting-started/advanced-options/sending-media-source-data.md)

[Sending User Segments / User Info](/getting-started/advanced-options/sending-user-segments-user-info.md)

### 2. User Login

Upon initializing the SDK, the mandatory step is to log in the user. However, passing a user ID is optional and is only necessary when the publisher operates its own user system. This login process ensures that user interactions with the offerwall are accurately tracked and attributed within the application.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
import com.tyrads.sdk.Tyrads
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

CoroutineScope(Dispatchers.Main).launch {
    // Pass custom User ID (Recommended) or omit/null for device ID tracking
    val isSuccess = Tyrads.getInstance().loginUser(userID = "YOUR_CUSTOM_USER_ID")
    if (isSuccess) {
        // Login complete
    }
}
```

{% endtab %}

{% tab title="Java" %}

```java
Timport com.tyrads.sdk.Tyrads;
import com.tyrads.sdk.TyradsLoginCallback;

Tyrads.getInstance().loginUser("YOUR_CUSTOM_USER_ID", new TyradsLoginCallback() {
    @Override
    public void onSuccess(boolean isNewUser) {
        // Login complete. isNewUser indicates if this profile was just created
    }

    @Override
    public void onFailure(String error) {
        // Handle login failure
    }
});
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The generated user ID from the SDK is based on the device identifier (GAID/OAID/IDFA)

* If your app user resets the device identifier, your user will lose the progress data
* If the SDK can't access the device identifier, it will generate its own device identifier and store it in the app storage. If this is the case, your app user will lose the progress data when the user uninstalls the app
* **If you send us your userId within userId field from your backend we will save this and even if the user changes their device ID we will keep their progress.** 
  {% endhint %}

### 3. Show Offerwall 

Once the SDK is initialized and the user is logged in (if applicable), you can display the offerwall to the user. This typically involves calling a function provided by the Tyrads SDK, such as showOffers. The offerwall is where users can engage with various offers, advertisements, or promotions provided by Tyrads, potentially earning rewards or incentives in the process.

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
import com.tyrads.sdk.Tyrads
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

CoroutineScope(Dispatchers.Main).launch {
    // Launches full offerwall overlay
    Tyrads.getInstance().showOffers(
        route = null,      // Optional deep link route
        campaignID = null  // Optional campaign ID
    )
}
```

{% endtab %}

{% tab title="Java" %}

```java
import com.tyrads.sdk.Tyrads;
import com.tyrads.sdk.TyradsCallback;

Tyrads.getInstance().showOffers(
    null, // route
    null, // campaignID
    new TyradsCallback() {
        @Override
        public void onSuccess() {
            // Offerwall shown successfully
        }

        @Override
        public void onFailure(String error) {
            // Failed to launch offerwall
        }
    }
);
```

{% endtab %}
{% endtabs %}