Kotlin SDK

The Kotlin SDK provides a straightforward way to ingest events on the server-side.

Setup

Add required repositories

repositories {
    mavenCentral()
    
    // Jitpack for Coxwave Align SDK itself
    maven {
        url = uri("https://jitpack.io")
    }
    
    // Buf for Coxwave Align API Schema (Dependencies)
    maven {
        name = "buf"
        url = uri("https://buf.build/gen/maven")
    }
}

Add dependencies

dependencies {
    ...

    // SDK
    implementation("com.github.coxwave:alignai-sdk-kotlin:0.4.0")
    
    // SDK Dependencies
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("com.connectrpc:connect-kotlin-okhttp:0.7.1")
    implementation("com.connectrpc:connect-kotlin-google-java-ext:0.7.1")
    implementation("com.google.protobuf:protobuf-kotlin:4.28.3")
    implementation("build.buf.gen:impaction-ai_ingestion_connectrpc_kotlin:0.7.1.1.20240908234409.342910308823")
    implementation("build.buf.gen:impaction-ai_ingestion_protocolbuffers_kotlin:28.3.0.2.20240908234409.342910308823")
    
    // Coroutine
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
}

Initialize the SDK

To start, initialize the SDK using your API key and Project ID:

import com.github.coxwave.alignsdkkotlin.AlignAI
import com.github.coxwave.alignsdkkotlin.Configuration

// ...

val sdk = AlignAI(Configuration(
   projectId = "PROJECT_ID",
   apiKey = "API_KEY",
))

Create an Event

Once you initialize the SDK, create events at the pre-defined circumstances as appropriate. Below are events that can be created:

Event: IdentifyUser

Send the IdentifyUserEvent to record detailed user information.

The recommended use cases of this method are:

When a user first signs up for your service.
When a user updates their profile information such as email address or display name.
When OpenSessionEvent is created.
- While the IdentifyUserEvent can be created during sign-up or profile updates, an alternate strategy is to initially avoid the IdentifyUserEvent altogether. Given that the OpenSessionEvent inherently demands a userId, you can solely focus on this event. By doing so, the user's identification process will be managed seamlessly.

The userId is the distinct identifier given to every user in your service. You can employ your existing user ID or create a new one using methods similar to uuid.

On the other hand, userDisplayName is the user's display name shown on the dashboard.

userId (String, required): Unique user ID used internally. This ID will not be displayed on the dashboard. Max 64 chars allowed.
userDisplayName (String): User display name shown on the dashboard. It's advised to use the user's nickname for this purpose. If a nickname isn't available, alternatives like the email address can be used. This field does not have to be unique. Otherwise, it defaults to empty string. Max 64 chars allowed.
userEmail (String): User email address. Max 256 chars allowed.
userIp (String): User IPv4 address. Provide either ip or country code for user location. If both are given, country code overrides ip.
userCountryCode (String): User country code in ISO Alpha-2. Provide either ip or country code for user location. If both are given, country code overrides ip.
userCreateTime (java.time.Instant): User creation time.
customProperties (Map<string, string>): Custom Properties(Metadata) of user. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import com.github.coxwave.alignsdkkotlin.events.IdentifyUserEvent


IdentifyUserEvent(
   userId = "USER_ID",
   userDisplayName = "USER_DISPLAY_NAME",
   userEmail = "USER_EMAIL",
   userCountryCode = "ALPHA2_COUNTRY_CODE",
   userIp = "USER_IP",
   userCreateTime = Instant.now(),
)

Event: OpenSession

Send the OpenSessionEvent to record the initiation of a session.

sessionId (String, required): Session ID. Max 64 chars allowed.
userId (String, required): User ID that the session belongs to. Max 64 chars allowed.
assistantId (String): Assistant ID, if any. By default, 'DEFAULT' will be used. Max 64 chars allowed.
customProperties (Map<string, string>): Custom Properties(Metadata) of session. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import com.github.coxwave.alignsdkkotlin.events.OpenSessionEvent


OpenSessionEvent(
   sessionId = "SESSION_ID",
   userId = "USER_ID",
   assistantId = "ASSISTANT_ID",
)

Event: CreateMessage

Send the CreateMessageEvent method to record an individual message within a session.

sessionId (String, required): Session ID the message belongs to. Max 64 chars allowed.
messageIndex (UInt, required): Message index used to sort messages in a chronological order within a session. Must be unique within a session and should be a positive integer. Max 64 chars allowed.
role (com.github.coxwave.alignsdkkotlin.events.MessageRole, required): .USER or .ASSISTANT
content (String, required): Content of the message.
customProperties (Map<string, string>): Custom Properties(Metadata) of message. Key should match pattern ^[a-zA-Z][a-zA-Z0-9_]{0,63}$. Max 256 chars allowed for value. Up to 10 properties are allowed. (This is merely a global limit. Please verify your project limit on your settings page.)

import com.github.coxwave.alignsdkkotlin.events.CreateMessageEvent
import com.github.coxwave.alignsdkkotlin.events.MessageRole


CreateMessageEvent(
   sessionId = "SESSION_ID",
   messageIndex = 1u,
   role = MessageRole.USER,
   content = "MESSAGE_CONTENT"
)

Event: CloseSession

Send the CloseSessionEvent to record the end of a session.

After 30 minutes of inactivity, the session will close automatically.

sessionId (string, required): Session ID. Max 64 chars allowed.

import com.github.coxwave.alignsdkkotlin.events.CloseSessionEvent


CloseSessionEvent(
   sessionId = "SESSION_ID",
)

Event: CreateSessionFeedbackEvent

Send the CreateSessionFeedbackEvent method to record an individual feedback within a session.

sessionId (String, required): The ID of the session to which the feedback belongs. Maximum 64 characters allowed.
feedbackType (String, required): The type of feedback, such as thumbs_up or thumbs_down, indicating the nature of the feedback.

import com.github.coxwave.alignsdkkotlin.events.CreateSessionFeedbackEvent


CreateSessionFeedbackEvent(
    sessionId = "SESSION_ID",
    feedbackType = "thumbs_up"
)

Event: CreateMessageFeedbackEvent

Send the CreateMessageFeedbackEvent method to record an individual feedback within a message.

sessionId (String, required): The ID of the session to which the feedback belongs. Maximum 64 characters allowed.
messageIndex (UInt, required): The index of the message used to sort messages in chronological order within a session. messageIndex also indicates the message to which the feedback belongs. It must be unique within a session and should be a positive integer. A maximum of 64 characters is allowed.
feedbackType (String, required): The type of feedback, such as thumbs_up or thumbs_down, indicating the nature of the feedback.

import com.github.coxwave.alignsdkkotlin.events.CreateMessageFeedbackEvent


CreateMessageFeedbackEvent(
    sessionId    = "SESSION_ID",
    messageIndex = 1,
    feedbackType = "thumbs_up"
)

Send Events

Once you create an event, send it to Coxwave Align using the collectEvents method.

launch {
   // You can send a single event
   sdk.collectEvents(listOf(event));
   
   // or, you can send multiple events at once
   sdk.collectEvents(listOf(event1, event2, event3));
}

If sdk got unsuccessful response, com.github.coxwave.alignsdkkotlin.APIException will be thrown.

Last modified: 23 June 2025