Purpose
Create and present Encore offers using a fluent builder API. Fetches available offers for the current user and presents them in a native offer sheet.
Signature
// Create a placement
fun placement(id: String? = null): PlacementBuilder
// Present the offer (suspend)
suspend fun PlacementBuilder.show(activity: Activity): PresentationResult
// Present the offer (fire-and-forget)
fun PlacementBuilder.show(activity: Activity, scope: CoroutineScope)
PlacementBuilder Methods
| Method | Parameters | Description |
|---|
placement() | id: String? | Creates a placement with optional identifier. If omitted, auto-generates a unique ID |
show() | activity: Activity | Suspending — fetches offers and presents the offer sheet. Returns PresentationResult |
show() | activity: Activity, scope: CoroutineScope | Fire-and-forget — launches show() in the provided coroutine scope |
Returns
show(activity) returns a PresentationResult:
| Result | Description |
|---|
PresentationResult.Completed | User completed an offer flow (tapped CTA, opened link) |
PresentationResult.Dismissed | User dismissed without completing |
PresentationResult.NoOffers | No offers available for this user |
Usage
Suspend (recommended)
lifecycleScope.launch {
val result = Encore.placement("cancel_flow").show(this@MainActivity)
when (result) {
is PresentationResult.Completed -> {
Log.d("Encore", "Offer completed: ${result.offerId}")
}
is PresentationResult.Dismissed -> {
proceedWithCancellation()
}
is PresentationResult.NoOffers -> {
proceedWithCancellation()
}
}
}
Fire-and-forget
// When you don't need the result — handlers via onPurchaseRequest/onPassthrough
Encore.placement("cancel_flow").show(this, lifecycleScope)
With named placement for analytics
// Placement ID appears in your analytics and global listeners
Encore.placement("onboarding_upsell").show(this, lifecycleScope)
Encore.placement("cancel_flow").show(this, lifecycleScope)
Encore.placement("settings_upgrade").show(this, lifecycleScope)
Provide a descriptive placement ID to identify this specific placement in your analytics. If omitted, a random ID is generated.
The show() suspend variant throws EncoreError.Integration.NotConfigured if the SDK hasn’t been configured. The fire-and-forget variant catches and logs errors internally.