Skip to main content
Get the Pillow SDK running in your Android app in a few minutes.

​
Prerequisites

  • Android API 24+ (Android 7.0)
  • A publishable API key — see Apps and API keys to create one
  • A study set to live mode — copy its ID from the Integration tab

​
Installation

Add the Pillow SDK to your app-level build.gradle.kts: 
dependencies {
    implementation("so.pillow:pillow-android-sdk:0.1.3")
}
Make sure mavenCentral() is in your repositories block.

​
Initialize the SDK

Call initialize() once at app startup, typically in your Application class or main Activity: 
import so.pillow.sdk.PillowSDK

PillowSDK.initialize(
    context = applicationContext,
    publishableKey = "pk_live_..."
)
Initialize the SDK only once. Calling initialize() multiple times is a no-op.

​
Present your first study

Show a study to the user by calling presentStudy() from any Activity: 
import so.pillow.sdk.PillowStudy

PillowSDK.presentStudy(
    activity = this,
    study = PillowStudy(id = "your-study-id-here")
)
The study opens as a modal overlay. The user can complete the conversation and dismiss it when done.

​
Handle microphone permissions

If your study uses voice input, forward the permission result to the SDK: 
override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    PillowSDK.onRequestPermissionsResult(requestCode, permissions, grantResults)
}
If you skip this step, the microphone button won’t appear in studies that support voice input.

​
Full example

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import so.pillow.sdk.PillowSDK
import so.pillow.sdk.PillowStudy

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        PillowSDK.initialize(
            context = applicationContext,
            publishableKey = "pk_live_..."
        )

        PillowSDK.setExternalId("user_123")
        PillowSDK.setUserProperty("plan", "pro")

PillowSDK.presentStudy(
            activity = this,
            study = PillowStudy(id = "your-study-id-here")
        )
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        PillowSDK.onRequestPermissionsResult(requestCode, permissions, grantResults)
    }
}
If you want lifecycle callbacks, pass an anonymous PillowStudyListener object to presentStudy(). That is the normal Android integration pattern.

​
What’s next?

Identify users

Set external IDs and user properties.

Present studies

Control when and how studies appear.

Session management

Handle logout and session lifecycle.