Overview

The Appnomix Commerce SDK is a mobile library designed to help brands deepen their relationship with customers by placing the brand prominently on the users' mobile phones.

On Android, the SDK uses the Accessibility Service to track browser interactions, such as the currently rendered page. To enable this service, both the host application and the SDK must coordinate to ensure the user grants the necessary permission.

At this time, the SDK supports interactions only within Google Chrome. Support for additional browsers can be added upon request.

Key links

For any additonal questions regarding the integration, outside the scope of this document, please contact [email protected].

You can also see how the SDK can be integrated by having a look at our: Appnomix Sample App

Getting Started

Minimum requirements

• Android minSDK version 5.0 (API 21)
• Android compileSDK version 15 (API 35)

Installing the SDK

1. Add the SDK dependency inside your current Android Gradle project, linking against the latest version:

repositories {
    mavenCentral() // use mavenCentral as the source of this dependency
}

android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  
    // backwards support for newer Java APIs the SDK might be using (e.g. SDK using Java_18, while host app using Java_17)
	  isCoreLibraryDesugaringEnabled = true
 }
}

dependencies {
    // other project-specific dependencies above/after this
    implementation("app.appnomix:sdk:1.7.1")
    
    // backwards support for newer Java APIs the SDK might be using
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
}

2. Inside your app's main Android Application class, setup the Appnomix SDK by providing the needed data, as depicted below.

import android.app.Application
import app.appnomix.sdk.external.CouponsSdkFacade

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        CouponsSdkFacade.setup(
            CouponsSdkFacade.Config(
                authToken = "token_received_from_appnomix",
                clientId = "clientId_received_from_appnomix"
            )
        )
    }
}

Starting the SDK

To request Accessibility Service access from the user, the application must launch the Onboarding flow, as depicted below, which explains the SDK’s features and the reasons why this permission is required.

import app.appnomix.sdk.external.CouponsSdkFacade
import app.appnomix.sdk.external.ExternalCoupon
import app.appnomix.sdk.external.SdkRequirement

class MainActivity : AppCompatActivity() {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // you can check for unmet requirements, before launching the onboarding, by requesting them from the SDK and checking if the returned list is empty.
    // val unmetRequirements = CouponsSdkFacade.unmetRequirements()
    
    // calling this will launch the onboarding, only if it wasn't finished before. if it has, it's a no-op 
    CouponsSdkFacade.launchSdkOnboardingActivity(this)
  }
}

Should you require more control or if you'd like to further fine-tune the onboarding experience for your users, you can also make use of the following functions the SDK is exposing:

1. CouponsSdkFacade.isAccessibilityServiceEnabled-> returns true if the service is enabled
2. CouponsSdkFacade.goToToAccessibilitySettings-> takes the user to the OS Accesibility Settings, directly where the needed permission, without needing to launch the onboarding flow.

You can customize the colors on the onboarding screen by passing a string JSON, similar to the one from the sample app via CouponsSdkFacade.launchSdkOnboardingActivity(activity, jsonString).

What's next

If the integration is successful and the user has granted Accessibility Permission, then upon visiting a website in the Chrome browser where the SDK identifies valid deals and can interact with the HTML selectors, the user may see the following elements appear on their screen.

Tracking the CTA and installation

Event tracking instructions and code samples

Should your app require more granular control regaring the SDK's Onboarding process, you can register an event listener which will fire when the onboarding is either started, finished or abandoned, as depicted below:

CouponsSdkFacade.registerEventListener(object : AppnomixEventListener {
    override fun onAppnomixEvent(event: AppnomixEvent) {
        when (event) {
            AppnomixEvent.ONBOARDING_STARTED -> {
                Log.i("AppnomixSample", "User started Appnomix Onboarding")
            }

            AppnomixEvent.ONBOARDING_ABANDONED -> {
                Log.i(
                    "AppnomixSample",
                    "User left Appnomix Onboarding without activating the extension"
                )
            }

            AppnomixEvent.ONBOARDING_FINISHED -> {
                Log.i(
                    "AppnomixSample",
                    "User left Appnomix Onboarding and the extension is Activated"
                )
            }
        }
    }
})

How to detect successful install and track it

When presenting the offer to your users (e.g., as part of a list that includes Appnomix among other providers), you should call the following function to ensure accurate funnel tracking. The function accepts a string parameter representing the context in which the offer was shown—such as “my offers”, “special offers”, “cooldown time”, or “new level unlocked”—based on what’s relevant to your app.

CouponsSdkFacade.trackOfferDisplay("Marble Crush - Next Level")

Changing the Language

The SDK accepts ISO 639-1 language codes through its setup function. Currently, only “en” and “de” are supported. If no language code is provided, the SDK defaults to “en”.

import android.app.Application
import app.appnomix.sdk.external.CouponsSdkFacade

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        CouponsSdkFacade.setup(
            CouponsSdkFacade.Config(
                authToken = "token_received_from_appnomix",
                clientId = "clientId_received_from_appnomix",
                language = "de"
            )
        )
    }
}

API Reference