Skip to content

Contextual (AndroidX) Setup

The Android SDK allows you to quickly build a no-code personalised in-app communication to your users in your Android app. We provide wonderful and customisable elements that you can use. We also expose the low-level APIs that underpin those UIs so that you can build fully custom experiences to delight your users.

You can find an example app with the sdk integrated here

Prerequisites

  1. Your App must be targeted for at least Nougat (API 24) and above;
  2. Contextual uses Java 11 features, please make sure your app uses it as well app/build.gradle:
1
2
3
4
5
6
7
8
9
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

Step 1 - Project level build.gradle

Please add the Contextual repository to your build.gradle

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
allprojects {
    repositories {
        maven {
            url "https://repo.contextu.al/sdk/contextual/"
        }
        google()
        mavenCentral()

    }
}

By default, new Android Studio projects specify Google's Maven repository, and the Maven central repository as repository locations in the project's settings.gradle file in dependencyResolutionManagement block, as shown below.

1
2
3
4
5
6
7
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

Remove dependencyResolutionManagement block from setting.gradle if Contextual repository is added to project level build.gradle. *For new project contextual repository should be added to settings.gradle only shown as below.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://repo.contextu.al/sdk/contextual/"
        }
    }
}

Step 2 - Setup Contextual

This will link the Contextual SDK with your app.

You need to add this either to the root of your app's build.gradle or under the android {} task

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
apply plugin: 'com.android.application'

android { ... }

dependencies {
  // ...

  // Contextual Android SDK
  implementation 'com.contextu.al:contextual:3+'
}

Contextual UI is based on Google's Material Components library. Please ensure your app's theme inherits from Theme.MaterialComponents or its subthemes.

Also, please, check if your app uses a version equal or more recent to 1.1.0

1
2
3
dependencies {
    implementation (group: "com.google.android.material", name: "material", version: "1.1.0")
}

You need to make sure that inside your app/res/values/styles.xml (or equivalent) the parent of AppTheme is part of the Theme.MaterialComponents theme. Here is an example from the Wikipedia's app:

1
2
3
4
5
6
   <style name="BaseAppTheme" parent="Theme.MaterialComponents.Light.NoActionBar"> 
        <...>
    </style>
    <style name="AppTheme" parent="BaseAppTheme">
        <...>
    </style>

(If you are having issues with this please check instructions here, specially step 2)

Step 3 - Integrating Contextual to your app

There are 2 ways to integrate Contextual into your app.

  1. Set your Contextual AppKey in your AndroidManifest.xml file

Under the application tag, add the following meta-data tag replacing APP_KEY with your app key:

1
2
3
4
5
6
7
    <application
        android:name=".MainApplication">

        <meta-data
            android:name="com.contextu.al.APP_KEY"
            android:value="APP_KEY_HERE" />
    </application>
  1. Init via code
1
Contextual.init(application, "APP_KEY_HERE")

This is the recommended way to initialise if you have plans to use custom tags. We do offer callbacks to signal when initialisation was successful.

1
2
3
4
5
6
7
8
9
Contextual.init(application, "APP_KEY_HERE", object : CtxEventObserver {
            override fun onInstallRegistered(installId: UUID, context: Context) {
                // TODO: tag users here
            }

            override fun onInstallRegisterError(errorMsg: String) {
                // TODO: handle error here
            }
        })
  1. Identifying your users At this point Contextual is fully integrated on you app, but to make it easier to identify your users and use the full capabilities of the Contextual SDK you can use the following method at any part of your code after performing the integration.

Java:

1
Contextual.tagUserId("BestUserEver#24");

Kotlin:

1
Contextual.tagUserId("BestUserEver#24")

Using Custom Fonts

  1. Make sure you have the custom font you'd like to use in the project path 'app/assets/fonts'
  2. on your dashboard in the 'Content' section type in the font file name into the 'Font family' text field and press enter, eg "roboto_regular.ttf"
  3. Save the guide, then you would see the guide with the updated font family on your device.

NOTE: - Open-Type fonts(.otf) will only render for devices runing android 8.0 upwards. - Adding the file extension is necessary for proper rendering of font.

Next Steps

Tagging

Learn how to tag your users

Need help? Contact Support

Check out our changelog

Last update: 2024-01-14