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(): PresentationResult
// Present the offer (fire-and-forget)
fun PlacementBuilder.show(scope: CoroutineScope)
PlacementBuilder Methods
| Method | Parameters | Description |
|---|
placement() | id: String? | Creates a placement with optional identifier. If omitted, auto-generates a unique ID |
show() | — | Suspending — fetches offers and presents the offer sheet. Returns PresentationResult |
show() | scope: CoroutineScope | Fire-and-forget — launches show() in the provided coroutine scope |
Returns
show() returns a PresentationResult:
| Result | Description |
|---|
PresentationResult.Granted | User completed an offer flow (tapped CTA, opened link) |
PresentationResult.NotGranted | User was not granted an offer |
Usage
Suspend (recommended)
lifecycleScope.launch {
val result = Encore.placement("cancel_flow").show()
when (result) {
is PresentationResult.Granted -> {
Log.d("Encore", "Offer granted: ${result.offerId}")
}
is PresentationResult.NotGranted -> {
proceedWithCancellation()
}
}
}
Fire-and-forget
// When you don't need the result — handlers via onPurchaseRequest/onPassthrough
Encore.placement("cancel_flow").show(lifecycleScope)
With named placement for analytics
// Placement ID appears in your analytics and global listeners
Encore.placement("onboarding_upsell").show(lifecycleScope)
Encore.placement("cancel_flow").show(lifecycleScope)
Encore.placement("settings_upgrade").show(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.