Skip to content
Optima docs
SDKsAndroid SDK

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

KeyTypeDefaultMeaning
keyString (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.
endpointString (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.
screenTrackingScreenTracking (AUTO | OFF)AUTOAUTO: 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.
debugBooleanfalseEnables 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.beforeDecisionBeforeDecision (BUFFER | SEND)BUFFERBUFFER: 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.sourceConsentSource (OPTIMA | CMP)OPTIMAOPTIMA: 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)WEBVIEWGoverns 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:

  1. beforeDecision is silently overridden to SEND no matter what you wrote — see OptimaConfig.Builder.build(): "source=CMP hands the decision to the CMP: buffering would wait for a decision that is not ours to make."
  2. The SDK stops declaring its own consent state (consent.set, consent.get().decisions) as the purposes array on outgoing requests. It still merges in whatever you feed consent.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 fieldMaps to
$context.urlurl (the app://<package>/<screen> convention — see chapter 5)
$context.titlescreen name
$props.session_idsession id
$props.session_startsession-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.

On this page