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

# Android SDK — Integration Guide

This guide covers everything an Android application needs to integrate the Wynta SDK: initialisation, user identity, event tracking, and lifecycle events.

***

### Table of Contents

1. Installation
2. Initialisation
3. User Identity
   * Anonymous (pre-login)
   * After login
   * Updating traits
   * Logout
4. Event Tracking
5. Automatic Lifecycle Events
6. Full Lifecycle Example
7. API Reference
8. Push Notification Templates
9. ProGuard Rules

***

### 1. Installation

#### Maven Central (recommended)

Add to your app-level `build.gradle` or `build.gradle.kts`:

```kotlin
dependencies {
    implementation("io.github.wynta-git:signal-android-sdk:1.6.4")
}
```

No extra repository config needed — Maven Central is included by default in all modern Android projects. Check [Maven Central](https://central.sonatype.com/artifact/io.github.wynta-git/signal-android-sdk) for the latest published version number.

#### Local AAR (offline / private distribution)

Copy `signalsdk-release.aar` into your project's `app/libs/` folder, then:

```kotlin
dependencies {
    implementation(files("libs/signalsdk-release.aar"))
    // Required transitive dependencies
    implementation("androidx.lifecycle:lifecycle-process:2.7.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}
```

***

### 2. Initialization

Call `SignalSDK.initSDK()` once from your `Application.onCreate()`. Never call it from an `Activity` — you'd re-initialize on every screen.

**1. Create your Application class:**

```kotlin
// MyApplication.kt
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        SignalSDK.initSDK(
            context = this,
            config  = SignalConfig(
                clientId     = "YOUR_CLIENT_ID",
                clientSecret = "YOUR_CLIENT_SECRET",
                debug        = BuildConfig.DEBUG,  // prints logs in debug builds only
                // Optional (1.4.2+) — push notification icon and accent color, see §8.2.
                smallIconResId         = R.drawable.ic_notification_icon,
                notificationColorResId = R.color.notification_accent
            )
        )
    }
}
```

**Java:** `SignalConfig` is a Kotlin class, so Java must pass every argument positionally in this order — `clientId, clientSecret, debug, onApiLog, smallIconResId, notificationColorResId`. Pass `null` for the ones you don't use. `onApiLog` is a Kotlin function type, so a Java lambda must `return null;`.

```java
// MyApplication.java
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        int smallIcon = getResources().getIdentifier("ic_notification_icon", "drawable", getPackageName());
        SignalSDK.INSTANCE.initSDK(this, new SignalConfig(
                "YOUR_CLIENT_ID",
                "YOUR_CLIENT_SECRET",
                BuildConfig.DEBUG,                 // debug
                apiLogEntry -> {                   // onApiLog (or null)
                    return null;
                },
                smallIcon != 0 ? smallIcon : null, // smallIconResId (or null)
                R.color.notification_accent        // notificationColorResId (or null)
        ));
    }
}
```

**2. Register it in `AndroidManifest.xml`:**

```xml
<application
    android:name=".MyApplication"
    ...>
```

**What `initSDK` does:**

* Stores credentials in memory
* Creates a stable session ID for this cold launch
* Starts the `ProcessLifecycleOwner` observer for automatic foreground/background events

After `initSDK`, always call `setIdentity` to attach a user ID before tracking events.

***

### 3. User Identity

Identity tells the SDK **who is using the app**. The SDK maintains one active identity at a time. It can be anonymous (a UUID you generate) or a real player ID after login.

#### 3.1 Anonymous (pre-login)

Call `setIdentity` right after `initSDK` with an anonymous UUID:

```kotlin
SignalSDK.setIdentity(
    IdentityPayload(userId = "anon-${UUID.randomUUID()}")
) { response ->
    // runs on main thread
    if (response.success) {
        // sdk_init + session_started + app_opened auto-tracked
    }
}
```

#### 3.2 After login

Pass the real player ID and as many traits as available:

```kotlin
SignalSDK.setIdentity(
    IdentityPayload(
        userId = "ply_776192",
        traits = PlayerTraits(
            email            = "player@example.com",
            firstName        = "Alex",
            lastName         = "Smith",
            dateOfBirth      = "1990-04-15",
            country          = "MT",
            currency         = "EUR",
            language         = "en",
            kycStatus        = "pending",
            vipLevel         = "bronze",
            accountStatus    = "active",
            registrationDate = "2026-05-18T14:38:00.000Z",
            brandId          = "brand_01"
        )
    )
)
```

#### 3.3 Updating traits

Call `setIdentity` any time to update specific traits — only include changed fields:

```kotlin
// KYC approved
SignalSDK.setIdentity(IdentityPayload(traits = PlayerTraits(kycStatus = "approved")))

// VIP upgrade
SignalSDK.setIdentity(IdentityPayload(traits = PlayerTraits(vipLevel = "gold")))

// Remove a trait
SignalSDK.setIdentity(IdentityPayload(unsetTraits = listOf("referral_code")))
```

#### 3.4 Logout

```kotlin
SignalSDK.sendEvent("logout") { _ ->
    SignalSDK.clearIdentity()
    // Re-identify with a new anonymous UUID so events can still be tracked
    SignalSDK.setIdentity(IdentityPayload(userId = "anon-${UUID.randomUUID()}"))
}
```

***

### 4. Event Tracking

```kotlin
SignalSDK.sendEvent(
    eventName  = "deposit_success",
    properties = mapOf(
        "amount"         to 100,
        "currency"       to "EUR",
        "transaction_id" to "txn_abc123"
    )
) { response ->
    Log.d("Signal", "tracked: ${response.success}")
}
```

The `callback` is optional — fire and forget is fine for most events:

```kotlin
SignalSDK.sendEvent("screen_view", mapOf("screen" to "Home"))
```

#### Common events

```kotlin
// Screen view
SignalSDK.sendEvent("screen_view", mapOf("screen_name" to "Home"))

// Button tap
SignalSDK.sendEvent("button_tap", mapOf("button_id" to "deposit_cta", "screen" to "Wallet"))

// Game started
SignalSDK.sendEvent("game_started", mapOf(
    "game_id"   to "slots_001",
    "game_name" to "Lucky Spin",
    "category"  to "slots"
))

// Deposit
SignalSDK.sendEvent("deposit_success", mapOf(
    "amount"         to 100,
    "currency"       to "EUR",
    "transaction_id" to "txn_abc123"
))

// Bonus claimed
SignalSDK.sendEvent("bonus_claimed", mapOf(
    "bonus_id"   to "welcome_bonus",
    "bonus_type" to "deposit_match"
))
```

***

### 5. Automatic Lifecycle Events

The SDK automatically tracks the following events — no code needed in your app:

| Event             | When fired                                              |
| ----------------- | ------------------------------------------------------- |
| `sdk_init`        | First `setIdentity` call after `initSDK`                |
| `session_started` | First `setIdentity` call after `initSDK`                |
| `app_opened`      | First `setIdentity` call after `initSDK`                |
| `app_foreground`  | App returns from background (after first `setIdentity`) |
| `app_background`  | App goes to background                                  |
| `session_ended`   | App goes to background                                  |

> `app_terminated` is **not** tracked. Android does not guarantee `onDestroy` fires before a process kill.

***

### 6. Full Lifecycle Example

```kotlin
// MyApplication.kt
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        SignalSDK.initSDK(this, SignalConfig(
            clientId     = "YOUR_CLIENT_ID",
            clientSecret = "YOUR_CLIENT_SECRET",
            debug        = BuildConfig.DEBUG
        ))
    }
}

// MainActivity.kt (or ViewModel)
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Set anonymous identity immediately
        SignalSDK.setIdentity(IdentityPayload(userId = "anon-${UUID.randomUUID()}")) { response ->
            if (response.success) {
                SignalSDK.sendEvent("screen_view", mapOf("screen_name" to "Home"))
            }
        }
    }
}

// After login
fun onLoginSuccess(player: Player) {
    SignalSDK.setIdentity(IdentityPayload(
        userId = player.id,
        traits = PlayerTraits(
            email         = player.email,
            firstName     = player.firstName,
            country       = player.country,
            currency      = player.currency,
            accountStatus = "active"
        )
    ))
    SignalSDK.sendEvent("login_success", mapOf("method" to "email"))
}

// After logout
fun onLogout() {
    SignalSDK.sendEvent("logout")
    SignalSDK.clearIdentity()
    SignalSDK.setIdentity(IdentityPayload(userId = "anon-${UUID.randomUUID()}"))
}
```

***

### 7. API Reference

#### `SignalSDK.initSDK(context, config)`

| Parameter                       | Type                    | Required | Description                                                                                                                                        |
| ------------------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`                       | `Context`               | Yes      | Application context                                                                                                                                |
| `config.clientId`               | `String`                | Yes      | Your Signal client ID                                                                                                                              |
| `config.clientSecret`           | `String`                | Yes      | Your Signal client secret                                                                                                                          |
| `config.debug`                  | `Boolean`               | No       | Enable console logging (default: `false`)                                                                                                          |
| `config.onApiLog`               | `(ApiLogEntry) -> Unit` | No       | Callback after every outbound API request — for debugging/monitoring (default: `null`)                                                             |
| `config.smallIconResId`         | `Int` (drawable res ID) | No       | Status-bar icon for push notifications (1.4.2+). Default: a drawable named `ic_notification_icon` if the app has one, else a system icon. See §8.2 |
| `config.notificationColorResId` | `Int` (color res ID)    | No       | Default accent color for push notifications — used when a push doesn't set `bg_color`, and to tint the small icon/app name (1.4.2+). See §8.2      |

***

#### `SignalSDK.setIdentity(payload, callback?)`

| Parameter             | Type                       | Description                                |
| --------------------- | -------------------------- | ------------------------------------------ |
| `payload.userId`      | `String?`                  | Player ID or anonymous UUID                |
| `payload.anonymousId` | `String?`                  | Pre-login anonymous ID for event stitching |
| `payload.fcmToken`    | `String?`                  | FCM push token                             |
| `payload.traits`      | `PlayerTraits?`            | Player profile attributes                  |
| `payload.unsetTraits` | `List<String>?`            | Trait keys to remove                       |
| `payload.timestamp`   | `String?`                  | ISO-8601 — defaults to now                 |
| `callback`            | `((SDKResponse) -> Unit)?` | Invoked on main thread                     |

**PlayerTraits fields:**

| Field              | Type                | Description                            |
| ------------------ | ------------------- | -------------------------------------- |
| `email`            | `String?`           | Player email                           |
| `phone`            | `String?`           | Phone in E.164 format                  |
| `firstName`        | `String?`           | First name                             |
| `lastName`         | `String?`           | Last name                              |
| `dateOfBirth`      | `String?`           | `YYYY-MM-DD`                           |
| `country`          | `String?`           | ISO 3166-1 alpha-2 (e.g. `MT`)         |
| `currency`         | `String?`           | ISO currency code (e.g. `EUR`)         |
| `language`         | `String?`           | Language code (e.g. `en`)              |
| `kycStatus`        | `String?`           | `pending`, `approved`, `rejected`      |
| `vipLevel`         | `String?`           | `bronze`, `silver`, `gold`, `platinum` |
| `accountStatus`    | `String?`           | `active`, `suspended`, `closed`        |
| `registrationDate` | `String?`           | ISO-8601 datetime                      |
| `brandId`          | `String?`           | Brand/operator identifier              |
| `custom`           | `Map<String, Any?>` | Any additional key-value pairs         |

***

#### `SignalSDK.clearIdentity()`

Clears the active `userId`. Call on logout.

***

#### `SignalSDK.sendEvent(eventName, properties?, callback?)`

| Parameter    | Type                       | Required | Description            |
| ------------ | -------------------------- | -------- | ---------------------- |
| `eventName`  | `String`                   | Yes      | Non-empty event name   |
| `properties` | `Map<String, Any?>`        | No       | Key-value event data   |
| `callback`   | `((SDKResponse) -> Unit)?` | No       | Invoked on main thread |

***

#### `SDKResponse`

```kotlin
data class SDKResponse(
    val success: Boolean,
    val accepted: Int? = null,   // events accepted (track calls)
    val rejected: Int? = null,   // events rejected (track calls)
    val error: String? = null    // error message if success = false
)
```

***

### 8. Push Notification Templates

The SDK renders campaign push notifications itself — the host app forwards the raw FCM payload to `handleRemoteMessage`, and the SDK parses it, builds the notification (with a custom, rounded-card layout for `branded` and `hero_banner`, not just plain `NotificationCompat` styles), and posts it. **The SDK does not own an FCM manifest entry** — host apps like this one typically already have their own `FirebaseMessagingService` (for MoEngage, Freshchat, etc.), and Android only allows one per app. Forward the raw data map with one line from your own service:

```kotlin
class MyFirebaseMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        super.onMessageReceived(remoteMessage)
        SignalSDK.handleRemoteMessage(remoteMessage.data)
    }
}
```

If `title`/`body` aren't present in the data map, `handleRemoteMessage` treats it as not a template push and does nothing — safe to call unconditionally on every message, including ones from other providers.

#### 8.1 Payload contract

| Field                                                     | Scope                 | Description                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template`                                                | all                   | `"standard"` \| `"branded"` \| `"hero_banner"` (case-insensitive; unrecognized values fall back to `standard`)                                                                                                                                                                    |
| `title` / `content`                                       | all                   | Required — the notification text. `content` is the current field name for the body text; `body` is still accepted as a fallback for older campaigns                                                                                                                               |
| `bg_color`                                                | `branded` only        | e.g. `"#3A4CE0"` — fills the whole card (rounded corners on API 31+, flat fill pre-31), ignored for other templates. `accentColorHex` is still accepted as a fallback                                                                                                             |
| `image_url`                                               | `standard`, `branded` | "Add a rich image": shown full width above the title/body in the expanded notification (the collapsed view stays text-only). If absent or the download fails, the push shows without an image. Branded no longer shows an icon beside the text                                    |
| `banner_url`                                              | `hero_banner` only    | Full-bleed image with title/body overlaid directly at the bottom; on API 31+ the card is sized to the image's real aspect ratio so it isn't cropped. Falls back to the `standard` layout if the download fails or the field is absent. `imageUrl` is still accepted as a fallback |
| `text_color`                                              | all                   | e.g. `"#FFFFFF"` — overrides the title/body text color on all three templates (unlike `bg_color`/`banner_url`/the rich image, not scoped to one template). Ignored if invalid/absent, in which case each template's default text color applies                                    |
| `notification_tap_type`                                   | all                   | `"dismiss"` \| `"deeplink"` \| `"share"` \| `"call"` \| `"track_event"` — see 8.3                                                                                                                                                                                                 |
| `notification_tap_action_1` / `notification_tap_action_2` | all                   | Opaque strings the app interprets based on `notification_tap_type` (e.g. a deep-link screen name)                                                                                                                                                                                 |

#### 8.2 Icon and color configuration

By default the small icon uses a drawable named `ic_notification_icon` if your app provides one (avoids Android's monochrome-silhouette rendering of full-color launcher icons), falling back to a system icon otherwise. Both the icon and a default accent color (used when a push doesn't set `bg_color`, and to tint the small icon/app-name chrome on every template) can be set explicitly at init:

```kotlin
SignalSDK.initSDK(
    context = this,
    config = SignalConfig(
        clientId = "...",
        clientSecret = "...",
        smallIconResId = R.drawable.ic_my_notification_icon,   // optional, overrides the naming convention
        notificationColorResId = R.color.brand_accent           // optional
    )
)
```

**Providing `ic_notification_icon` (the default, no code needed):** add a drawable with exactly this name to the **app** module:

```
app/src/main/res/drawable/ic_notification_icon.xml        ← vector drawable (recommended), or PNGs:
app/src/main/res/drawable-mdpi/ic_notification_icon.png    (24×24)
app/src/main/res/drawable-hdpi/ic_notification_icon.png    (36×36)
app/src/main/res/drawable-xhdpi/ic_notification_icon.png   (48×48)
app/src/main/res/drawable-xxhdpi/ic_notification_icon.png  (72×72)
app/src/main/res/drawable-xxxhdpi/ic_notification_icon.png (96×96)
```

* It must be in a `drawable*` folder (not `mipmap`) and be a **white shape on a transparent background** — Android renders the status-bar icon from the alpha channel only, so a full-color launcher icon becomes a blob.
* Without it (and without `smallIconResId`), notifications still work but show a generic system icon.
* `notificationColorResId` is a normal color resource, e.g. `<color name="notification_accent">#2F6BFF</color>` in `res/values/colors.xml`.

#### 8.3 Tap handling & deep links

The SDK only special-cases `notification_tap_type == "dismiss"` — the notification is posted with no content intent, so tapping it just clears it. **Every other value is opaque to the SDK.** For all of them, the SDK attaches `notification_tap_type`, `notification_tap_action_1`, and `notification_tap_action_2` as extras on the launch intent (alongside the existing `campaign_id`/`deep_link`/etc.), and the app is responsible for reading them and deciding what to do — the SDK does not navigate, open a dialer, or show a share sheet itself.

A typical app has a single place where the target screen for a `"deeplink"` tap gets decided — e.g. in `MainActivity`:

```kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    if (intent.getStringExtra("notification_tap_type")?.equals("deeplink", ignoreCase = true) == true) {
        val screen = intent.getStringExtra("notification_tap_action_1")
        // ...route to `screen`, however your app's navigation is structured
    }
}
```

`notification_tap_type`/`notification_tap_action_1`/`notification_tap_action_2` are also included automatically in the `notification_clicked`/`notification_opened` events fired by `handleNotificationClick`, so they're visible in analytics regardless of whether the app acts on them.

***

### 9. ProGuard Rules

If you use R8/ProGuard, add these rules to your `proguard-rules.pro`:

```proguard
# Signal Android SDK
-keep class com.signalsdk.** { *; }
-keepnames class com.signalsdk.**
```

The SDK ships a `consumer-rules.pro` that applies these automatically when integrated via Gradle — manual rules are only needed for AAR integration.

***

### Notes

* **`initSDK` must be called from `Application.onCreate()`**, not from an Activity.
* **`setIdentity` must be called after `initSDK`** before any events can be tracked.
* **Events do not require login** — anonymous identity is sufficient.
* **`setIdentity` is additive** — only passed fields are updated; the rest stay unchanged.
* **The callback is always invoked on the main thread** — safe to update UI directly.
