Usage & Integration Guide

To fully integrate the Testogethr SDK into your application, you need to initialize the SDK, configure your Android Manifest to capture Testogethr Deep Links, start test sessions, register your event schemas, and finally, track those events.

1. Initialization

The SDK must be initialized as early as possible in your application's lifecycle (e.g., inside the onCreate method of your custom Application class).

import android.util.Log
import com.testogethr.sdk.TestogethrSdk
import com.testogethr.sdk.TestogethrConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        TestogethrSdk.initialize(
            sdkAccessToken = "YOUR_SDK_ACCESS_TOKEN",
            config = TestogethrConfig(applicationContext),
            debugLogger = { level, tag, msg, err -> 
                // Listen to internal SDK logs
                Log.d("Testogethr", "[$level] $tag: $msg", err)
            }
        )
    }
}

Parameters:

• sdkAccessToken (String): Your unique SDK access token obtained from the Testogethr dashboard.
• config (TestogethrConfig): The platform-specific configuration object. On Android, this extracts the appName, appIconBase64, appPackageOrBundleId, appVersion, and platformName automatically using the applicationContext.
• debugLogger (((String, String, String, Throwable?) -> Unit)?, Optional): A callback to listen to internal SDK logs for debugging your integration.

Environment Routing: Backend endpoint selection (dev, pilot, prod) is now controlled internally by SDK build flavor, not at runtime from initialize.

2. Configuring Android Manifest for Test Sessions

The Testogethr platform activates testing sessions by deep linking into your application. To intercept these deep links, you must add a specific intent-filter to your primary or launcher <activity> inside the AndroidManifest.xml.

<activity android:name=".MainActivity" ...>
    <!-- Your existing intent filters (e.g., MAIN, LAUNCHER) -->
    
    <!-- Testogethr: Listen for Test Session starts -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- URI pattern: your.application.id://testogethr -->
        <data android:scheme="${applicationId}" android:host="testogethr" />
    </intent-filter>
</activity>

3. Starting a Test Session

When the Testogethr app redirects the user to your app via the deep link, the URL will contain a sessionToken query parameter. You must extract this token in your activity and pass it to the SDK to activate the session.

import android.content.Intent
import com.testogethr.sdk.TestogethrSdk

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Ensure SDK is initialized first!
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent?) {
        val sessionToken = intent?.data?.getQueryParameter("sessionToken")
        if (sessionToken != null) {
            TestogethrSdk.get().startSession(sessionToken)
        }
    }
}

Parameters:

• sessionToken (String): The unique token identifying the test session, extracted from the deep link query parameters.

4. Registering your Event Schema (registerSchema)

Before tracking events, it is best practice to statically register what events your application is capable of tracking. This allows the Testogethr Campaign Engine to discover your events and use them as milestones for campaigns.

import com.testogethr.shared.models.api.sdk.DeclaredEvent
import com.testogethr.sdk.TestogethrSdk

val bossEvent = DeclaredEvent(
    name = "boss_defeated",
    description = "Fired when the final alien boss is beaten"
)

TestogethrSdk.get().registerSchema(
    isDiscoveryMode = true,
    events = listOf(bossEvent)
)

Parameters:

• isDiscoveryMode (Boolean): Defaults to true. When enabled, the SDK communicates with the backend to discover any dynamic configuration or rules associated with these events.
• events (List<DeclaredEvent>): A list of DeclaredEvent objects that your app might emit. A DeclaredEvent consists of a name (String) and a description (String).

5. Tracking Events (trackEvent)

During an active test session, when a user completes a milestone or an action that you want to track for rewards or analytics, use trackEvent.

import com.testogethr.sdk.TestogethrSdk
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive

// Tracking an event with JSON metadata payload
TestogethrSdk.get().trackEvent(
    event = bossEvent,
    metadata = JsonObject(
        mapOf("bossHealthRemaining" to JsonPrimitive(0))
    )
)

Parameters:

• event (DeclaredEvent) or eventName (String): You can pass the same DeclaredEvent object used in registerSchema (recommended), or pass the raw event name string.
• metadata (JsonObject?, Optional): Additional contextual data related to the event. This must be a kotlinx.serialization.json.JsonObject.

Validation: If you registered events via registerSchema(events = ...), trackEvent will reject event names that are not in that declared list.

Important: Events tracked when there is no active session (i.e., startSession was not called or the token expired) will simply be ignored or logged locally, ensuring no network overhead for standard production users.