AI_Index

Android SDK Wiki — AI Agent Index

This index helps AI agents find the right documentation page without reading the entire wiki. Read this file first, then load only the specific pages relevant to your task.

Page Origin

This wiki contains two types of pages:

• Shared docs (lowercase-hyphenated filenames) — Cross-SDK concept docs whose canonical source is the backend repo at public/js/tracking/full-stack-docs/ (concepts/ and guides/ subdirs). The same prose is synced into every Full Stack SDK wiki (JavaScript, PHP, Python, Ruby, Android, iOS), with each wiki keeping only its own language's code blocks. Do not edit them here — they are owned by the canonical source and any edit made here is overwritten on the next sync.
• Android-specific docs (CamelCase filenames) — Written for this SDK only: quickstart, installation, initialization, configuration, return types, code examples, offline behavior, tracking control, Google Play Data Safety, Java interop, and testing.

Getting Started

Page	When to read
How Convert Works	High-level overview of the Convert platform and SDKs
Architecture Overview	System architecture, module relationships, data flow
Data Model Reference	Entity relationships: Experience, Variation, Feature, Variable, Goal, Audience, Location
Quickstart Overview	Cross-SDK quickstart concepts before diving into Android-specific setup
Requirements & Constraints	SDK limitations, environment requirements, known constraints

Android SDK Reference

Page	When to read
Quickstart	Step-by-step Android setup and first experiment
Installation	Gradle dependency from Maven Central, JDK/SDK levels, R8, permissions
Initialization	ConvertSDK.builder(context), onReady, direct-data mode, event subscription
Configuration Options	Full builder option reference
Return Types & Models	Kotlin models (Variation, Feature), enums (FeatureStatus, GoalDataKey, LogLevel), PreviewParam, and feature-variable accessors
Code Examples	Complete Kotlin and Java examples for all SDK methods, including setPreview
Offline Behavior	On-disk JSON event queue, atomic drain, WorkManager retry, network-aware flush
Tracking Control	Consent: SDK-level toggle, per-call override, and zero-trace preview
Google Play Data Safety	Data Safety form mapping for SDK-generated data
Java Interop	Using the SDK from Java

Core Concepts (Shared)

Page	When to read
Experiences & Variations	A/B test structure, variation assignment, activation
Feature Flags	Feature flag evaluation, variable values, feature status
Bucketing Algorithm	Hash-based visitor assignment, traffic allocation, deterministic bucketing
Rule Evaluation & Targeting	Audience matching, location matching, scheduling rules
Segments	Visitor segmentation logic and custom segments
Data Management	Data access layer, project config, entity lookups
Event System	Event pub/sub, lifecycle hooks, custom events
API Communication & Tracking	HTTP communication, config fetching, event tracking, queue management

How-To Guides (Shared)

Page	When to read
Running Experiences	End-to-end guide: activate experiments, get variations for a visitor
Running Features	Feature flag usage: evaluate flags, get variable values
Tracking Conversions	Goal tracking, conversion events, revenue tracking
Visitor Context & Properties	Visitor identification, custom properties, cross-session persistence
Persistent DataStore	Custom data store integration for visitor state persistence
QA & Preview	Debug tokens for QA config visibility; preview links that force a specific variation
Mutually Exclusive Experiments	Preventing experiments from overlapping via the bucketed_into_experience_key audience rule
Direct Tracking Endpoint	Posting tracking events without an SDK
Troubleshooting	Common issues, debugging techniques, diagnostic steps

Contributing

Page	When to read
Testing	Robolectric unit tests, direct-data mode, log capture

Android-Specific Notes

Topic	Key difference from JS SDK
Initialization	ConvertSDK.builder(context).sdkKey("...").build() — fluent Builder, no public constructor
Async model	Coroutine SDK scope; onReady { ... } gates the first decision call. setPreview is the only suspend public method (JS returns a Promise)
Lifecycle events	READY fires once per instance; every later successful refresh fires CONFIG_UPDATED
HTTP	OkHttp via OkHttpClientAdapter; every request carries a non-overridable User-Agent: ConvertAgent/1.0
Visitor persistence	App-scoped UUID v4 in SharedPreferences; sticky decisions persist per visitor
Config cache	Last-good config cached to an internal-storage file for offline cold start; disabled entirely while debugToken is set
Offline queue	Durable JSON file (filesDir/convert-sdk/events.json) claimed atomically via EventQueue.drain, dual-locked (in-process Mutex + events.json.lock), WorkManager exponential-backoff flush, NetworkObserver
Bucketing layout	Version-gated in BucketingLayoutResolver: experience.version > 11 runs the anchored layout (BucketingManager.getBucketForVisitorAnchored), else the frozen packed cumulative walk. Hash path identical to the JS SDK either way
Mutual exclusion	bucketed_into_experience_key resolves through BucketedExperienceResolver, keyed by experience KEY — Android's StoreData.bucketing shape, a deliberate divergence from the JS SDK's numeric-id keying
Preview	ConvertContext.setPreview(experienceId, variationId) — per-context, one-way (no clear API), zero-trace for the whole context
Return types	Kotlin data classes (Variation, Feature) and enums; variables as JsonElement with scalar accessors
Java interop	@JvmOverloads, @JvmStatic, SAM-convertible EventCallback fun interface. setPreview needs a Kotlin bridge

Public API Surface (entry points)

ConvertSDK.builder(context): Builder
  Builder: sdkKey / sdkKeySecret / debugToken / data / environment /
           configEndpoint / trackEndpoint / dataRefreshInterval / batchSize /
           releaseInterval / hashSeed / maxTraffic / excludeExperienceIdHash /
           logLevel / trackingEnabled / cacheLevel / rulesKeysCaseSensitive /
           rulesNegation / rulesComparisonProcessor / networkSource / mapper
           -> build(): ConvertSDK
ConvertSDK
  ├── createContext() / createContext(visitorId) / createContext(visitorId, attributes)
  ├── onReady(callback)
  ├── on(event, EventCallback): SubscriptionToken / off(event, token | callback)
  └── setTrackingEnabled(bool) / isTrackingEnabled()
ConvertContext
  ├── runExperience(key, enableTracking=true): Variation?
  ├── runExperiences(enableTracking=true): List<Variation>
  ├── runFeature(key): Feature? / runFeatures(): List<Feature>
  ├── trackConversion(goalKey, goalData?, conversionSetting?)
  ├── hasGoal(goalKey): Boolean
  ├── suspend setPreview(experienceId, variationId): ConvertContext
  ├── setAttributes / setLocationProperties
  └── setDefaultSegments / setCustomSegments
PreviewParam.parse(value): Pair<experienceId, variationId>?   // @JvmStatic

Defaults that consumers most often get wrong: logLevel is DEBUG (not ERROR) and dataRefreshInterval is 300_000 ms (5 min). Both live in ConfigDefaults.