Configuration
Android SDK v1.4.0 — Configuration
OptimaConfig is built once, at Optima.init time, and is immutable
afterward — there is no way to change endpoint or screenTracking mid-run
short of a process restart. It uses a small nested-builder DSL:
Optima.init(
context,
OptimaConfig(key = "oek_shop_a1b2c3", endpoint = "https://edge.shop.example") {
screenTracking = ScreenTracking.AUTO
debug = false
consent {
beforeDecision = BeforeDecision.BUFFER
source = ConsentSource.OPTIMA
}
display {
htmlMode = HtmlMode.WEBVIEW
}
},
)Keys
| Key | Type | Default | Meaning |
|---|---|---|---|
key | String (constructor, required) | — | The Edge SDK key (oek_...). Validated non-blank at build time (OptimaConfig.key is required); sent as the X-Edge-Key header on every request. See The SDK key below for where it comes from. |
endpoint | String (constructor, required) | — | The base URL of your Optima Edge gateway, e.g. https://edge.shop.example. Must start with http (validated at build time: OptimaConfig.endpoint must be an absolute http(s) URL); a trailing slash is stripped for you. Every SDK request is <endpoint>/edge/v1/... — nothing else is ever called. |
screenTracking | ScreenTracking (AUTO | OFF) | AUTO | AUTO: the SDK calls screen(name) for you on every Activity resume, using the Activity's simple class name as the screen name, via ActivityLifecycleCallbacks/androidx.lifecycle-process. OFF: you call Optima.instance.screen(name) yourself wherever a screen change happens (useful in single-Activity/Compose-Navigation apps where every screen would otherwise be reported as the same Activity name). Either way, the launching Intent's deep link is captured for attribution when an Activity resumes with a new launching Intent — that part isn't gated by this setting. Dedup is on the Intent object, not the URL: re-resuming the same Intent (task switcher, back from another Activity) is ignored, while a new tap of an identical link (a recurring campaign with static UTMs) is captured again for the current session. For a singleTop/singleTask Activity, call setIntent(intent) in onNewIntent so the new tap is seen on the next resume. |
debug | Boolean | false | Enables verbose Log.d/Log.w output under the optima logcat tag: every enqueue, flush, server response, dropped item and internal error. Leave this off in release builds (or wire it to BuildConfig.DEBUG, see chapter 1) — it's not a data-plane switch, purely a local log-verbosity one. |
consent.beforeDecision | BeforeDecision (BUFFER | SEND) | BUFFER | BUFFER: hits queue in the on-disk outbox but are not flushed to the server until a consent decision exists (consent.get().decided == true) — the first consent.set(...) call unblocks the queue. SEND: hits flush immediately regardless of whether consent has been decided yet, i.e. "send now, purposes travel as soon as they're known." Forced to SEND automatically whenever consent.source = CMP — a CMP-driven app doesn't own the decision, so there's nothing of ours to buffer for; see the source row below. |
consent.source | ConsentSource (OPTIMA | CMP) | OPTIMA | OPTIMA: the SDK declares its own purposes array on every request, built from consent.get().decisions (see chapter 4 for the omit-vs-[] rule). CMP: the SDK never declares its own purposes — a served banner_consent content item is not rendered as the built-in banner but instead surfaces as a plain ContentItem event for you to route to your CMP SDK, and you drive consent entirely through consent.setKeys/setGCM/setTCF (the TCF string is still read automatically from IABTCF_TCString, see chapter 4). |
display.htmlMode (htmlMode inside the display { } block) | HtmlMode (WEBVIEW | OFF) | WEBVIEW | Governs only unstructured content items (raw operator-authored HTML/CSS/JS, the Web SDK's unstructured format). WEBVIEW: the Compose module's OptimaHost/OptimaSlot render them in an isolated WebView (JavaScript on, no shared cookies or DOM storage with the rest of the app — see chapter 5). OFF: unstructured items are never rendered; they still surface as ContentItem/ContentLoaded events if you want to do something else with them, or are silently skipped by the Compose renderers. |
The source = CMP rule, once more explicitly
Setting consent.source = ConsentSource.CMP is a one-way toggle on two
independent behaviours, both irreversible for the life of the config object:
beforeDecisionis silently overridden toSENDno matter what you wrote — seeOptimaConfig.Builder.build(): "source=CMPhands the decision to the CMP: buffering would wait for a decision that is not ours to make."- The SDK stops declaring its own consent state (
consent.set,consent.get().decisions) as thepurposesarray on outgoing requests. It still merges in whatever you feedconsent.setKeys/setGCM/setTCF.
Use source = CMP only when a separate, already-integrated CMP SDK (OneTrust,
Didomi, a TCF-compliant vendor, ...) is the actual system of record for
consent in your app. Otherwise leave source = OPTIMA and let the built-in
banner (see chapter 4) do the work.
The SDK key
Keys are created in the Optima console under Edge → SDK keys. The key's
platform determines which surfaces it can reach and how the edge worker
resolves the device to a profile — create (or ask your Optima operator to
create) a key on the mobile platform specifically for this app, not a
web key repurposed for mobile traffic. A web-platform key presented from
this SDK will generally still authenticate (the X-Edge-Key check doesn't
distinguish platforms at that layer) but content targeting, the tracking
entity resolution (edge_settings.mobile_entity_type /
mobile_device_identifier_key), and origin/App-ID allowlisting are all
platform-scoped server-side, so a mismatched platform key produces confusing
gaps rather than a clean error. See chapter 9 for
what a wrong-platform or revoked key looks like from the SDK's side.
The screen_view category mapping
Every screen() call becomes a track("screen_view", name, ...) hit under
the hood (see chapter 3). Like every other
tracking category, screen_view lands only if an operator has mapped it
in the Optima console — an unmapped category is dropped server-side as
unknown_category (counted in the track response's dropped array and
surfaced as a Track event, never a hard error). This is the same rule the
Web SDK's page_view category follows.
The recommended category mapping for screen_view (create this once, in the
Optima console's category-mapping screen, before shipping):
| Source field | Maps to |
|---|---|
$context.url | url (the app://<package>/<screen> convention — see chapter 5) |
$context.title | screen name |
$props.session_id | session id |
$props.session_start | session-start marker |
the UTM/click-id props (utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid) | attribution props |
Add your app's own event categories (add_to_cart, purchase, ...) the same
way — nothing about screen_view is special beyond being the one category
every install needs mapped for screenTracking = AUTO (or your manual
screen() calls) to be visible in analytics at all.