Quickstart

Quickstart

Popup definitions always come from the backend, so the fastest way to validate the SDK is to initialize it with a valid publicKey and let it fetch your popups at runtime. The demo apps already use that flow.

1. Initialize the SDK

Android

val options = InitOptions(
    debug = true,                              // SDK logs only — does NOT change the backend
    environment = Environment.Development,     // omit (or use Environment.Production) to hit prod
    popupOptions = PopupOptions(
        publicKey = "<your-public-key>"
    ),
    autoLaunch = true,
    provideLang = { "en" },
    metadata = mapOf("userId" to "demo-user")
)

val sdk = DeepdotsPopups().apply {
    initialize(options)
    setPath("/home")
}

environment controls the backend base URL (Environment.Production → https://api.deepdots.com, Environment.Development → https://api-dev.deepdots.com). It defaults to Production when omitted. debug controls SDK log output only and is independent of the environment.

After initialization the SDK exposes a read-only environment property on DeepdotsPopups, so host apps can assert which backend they are pointed at and surface it in their own diagnostics or logs.

Localized button labels

The popup’s built-in texts (buttons, Question X of Y, error notices and accessibility labels) follow the survey’s language once it loads, and provideLang until then. Supported locales: en, es, da, fi, no, sv, ar, bn, de, pt, fr (the languages the platform offers for a survey) plus zh-CN. Region tags such as es-ES, nb-NO, zh-Hans, or underscore variants like es_419 are accepted. Unsupported locales fall back to English. Arabic surveys mirror the popup layout right to left. Labels set in PopupDefinition.actions always take precedence over the built-in texts.

iOS

Swift does not see Kotlin default values, so every parameter of InitOptions and PopupOptions has to be passed, in this order. Use nil for the ones you do not need:

let options = InitOptions(
    debug: true,                               // SDK logs only — does NOT change the backend
    environment: Environment.development,      // use .production to hit prod
    mode: nil,                                 // ignored: popups always come from Deepdots
    popupOptions: PopupOptions(
        id: nil,
        publicKey: "<your-public-key>",
        popups: nil,                           // ignored: popups always come from Deepdots
        companyId: nil
    ),
    provideLang: { Locale.current.language.languageCode?.identifier ?? "en" },
    autoLaunch: true,
    storage: nil,                              // nil = persistent default (UserDefaults)
    trackingEnabled: true,                     // false to wait for consent
    analytics: nil,                            // AnalyticsKeys(...) to send analytics
    geolocation: true,
    contactAttributes: nil,
    renderChrome: true,
    showProgressBar: nil,                      // nil = follow the survey configuration
    metadata: ["userId": "demo-user"]
)

let instance = DeepdotsSDK.DeepdotsPopups()
instance.initialize(options: options)
instance.setPath(path: "/home")

2. Attach a platform context

The SDK needs a platform-specific context to render popup UI.

• Android example: sdk.attachContext(PlatformContext(this))
• iOS example: instance.attachContext(context: PlatformContext(viewController: root))

3. Keep the current path updated

The examples change the current path as the user navigates:

• /login
• /home
• /detail/1
• /detail/2
• /detail/3
• /detail/4

Path updates matter because path segmentation and some trigger flows depend on them.

4. Listen for lifecycle events

The SDK emits:

• popup_shown
• popup_clicked
• survey_completed

These are exposed through the Event enum and the Events helper.

5. Trigger or show popups manually if needed

The SDK can also show or trigger popups from host code:

sdk.show(
    ShowOptions(
        surveyId = "a9c8c170-bb1c-11f0-9d29-d5fe3dd521d0",
        productId = "02b809f20e024bce47c57f123cff8735"
    ),
    PlatformContext(activity)
)

What to validate first

• The publicKey is valid
• The host app updates setPath(...) as screens change
• The host app calls onScroll, triggerEvent, or other trigger helpers when relevant
• Event listeners are wired so the team can confirm popup lifecycle behavior

Before going to production, review the best practices.