Android

1. Obtain Private Credentials

Ask your Tappa representative to provide you with private credentials to access and use the Tappa SDK. The required credentials are:

• Campaign id: your app will have its own configuration and show custom content such as GIFs, stickers, keyboard themes, etc
• DataDog API key: used to de-obfuscate crash stack traces. More information can be found here: https://github.com/DataDog/dd-sdk-android-gradle-plugin

2. Add Dependency Repositories

These following repositories must be added:

1. https://repo.tappa.com/repository/maven-releases/ - artefact repository hosting the Tappa Keyboard SDK
2. https://adsbynimbus-public.s3.amazonaws.com/android/sdks - Nimbus SDK used by the Tappa Keyboard SDK to deliver ads
3. https://jitpack.io - public artefact repository which hosts other libraries that the SDK depends on

If dependency repositories in your Android project are set in settings.gradle add the following into it:

dependencyResolutionManagement {
	repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
	repositories {
		google()
		mavenCentral()
		maven { url 'https://jitpack.io' }
		// Tappa SDK
		maven {
			url = uri("https://repo.mocha.global/repository/maven-releases/")
		}
		// Nimbus SDK
		maven {
			url = uri("https://adsbynimbus-public.s3.amazonaws.com/android/sdks")
			credentials {
				username = "*"
			}
			content {
				includeGroup("com.adsbynimbus.openrtb")
				includeGroup("com.adsbynimbus.android")
				includeGroup("com.iab.omid.library.adsbynimbus")
			}
		}
	}
}

Otherwise define the repositories in the project-level build.gradle file:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
        maven {
            url "https://repo.tappa.com/repository/maven-releases/"
        }
        ...
    }
    ...
}

3. Set Compile, Minimum & Target SDK Values

In your app build.gradle file set:

• compileSdk and targetSdk to at least 34
• minSdk to 23

android {
    compileSdk 34
    defaultConfig {
        minSdk 23
        targetSdk 33
        ...
    }
    ...
}

4. Enable Kotlin KAPT

The SDK uses the kotlin-kapt gradle plugin, therefore it needs to be enabled in your app. In your app build.gradle add the kotlin-android and kotlin-kapt plugins after com.android.application:

plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'kotlin-kapt'
    ...
}

5. Set Java 17 Compatibility

In your app build.gradle file set Java 8 compatability options:

android {
	  compileOptions {
		    sourceCompatibility JavaVersion.VERSION_17
		    targetCompatibility JavaVersion.VERSION_17
	  }
	  kotlinOptions {
		    jvmTarget = JavaVersion.VERSION_17
	  }
    ...
}

6. Enable Android Data Binding

The SDK uses Android data binding, therefore it needs to be enabled in your project in your app build.gradle file:

android {
      buildFeatures {
          dataBinding true
    }
    ...
}

7. Add the Tappa Keyboard SDK Dependency

Add the dependency in your app build.gradle file:

dependencies {
	def SDK_VERSION = "3.+"

	// Tappa Keyboard SDK
	implementation "com.mocha.keyboard:keyboard-sdk:$SDK_VERSION"
	implementation "com.tappa:sdk:$SDK_VERSION"

	// Buttons
	implementation "com.mocha.keyboard:brand-logo-button:$SDK_VERSION"
	implementation "com.mocha.keyboard:clipboard-button:$SDK_VERSION"
	implementation "com.mocha.keyboard:social-hub:$SDK_VERSION"
	implementation "com.mocha.keyboard:themes-button:$SDK_VERSION"
	implementation "com.mocha.keyboard:web-link-button:$SDK_VERSION"
	implementation "com.mocha.keyboard:speech-to-text-button:$SDK_VERSION"
}

The SDK_VERSION is defined separately so it can be conveniently used across multiple dependencies. For example some toolbar buttons are provided as part of their own modules. The version must always be the same as the Keyboard SDK version.

8. Initialize the SDK

Call Call MochaApplicationExtensions.init in your application class .onCreate function (before calling any other Tappa SDK functions), and replace the campaignId property with your campaign identifier obtained in step 1:

Application Class

import android.app.Application
import com.mocha.keyboard.framework.MochaApplicationExtensions
import com.mocha.keyboard.framework.MonetizationConfig

class TappaApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        TappaSdk.start(
            context = this,
            campaignId = "nxb1a1Ja2nTRH95AXkDrbj"
        )
        ...
    }
}

If your project doesn't have an Application class, create one and reference it in AndroidManifest.xml:

<application
    android:name=".TappaApplication"
    ...

🚧

The SDK must be initialized before any other SDK calls are made. The SDK can be safely initialized multiple times.

9. Override Keyboard System Names

In your application strings.xml file define the following strings:

• mocha_keyboard_name - the keyboard display name in various places, such as during the onboarding or keyboard settings

• mocha_spell_checker_name - the name of the spell checker in system settings

• mocha_spell_checker_settings_name - the display name of the spell checker in system settings

	<string name="mocha_keyboard_name" tools:ignore="PrivateResource">Tappa Demo Keyboard</string>
	<string name="mocha_spell_checker_name" tools:ignore="PrivateResource">Tappa Demo Spell Checker</string>
	<string name="mocha_spell_checker_settings_name" tools:ignore="PrivateResource">Tappa Demo Spell Checker Settings</string>

📘

The tools:ignore="PrivateResource" attribute is provided to silence warnings in Android Studio about overriding strings from the Tappa library and can be safely used.

The above example is for the default localization locale. Tappa supports the following additional locales by default which include the resource folder name and language:

values-de : German
values-es : Spanish
values-fr : French
values-it : Italian
values-pt : Portuguese
values-ru : Russian
values-tr : Turkish

The values for these languages should be overridden as appropriate.

10. Support DataDog Crash Reports

DataDog is required to get de-obfuscated crash stack traces.

Add the following statements to your app build.gradle file:

plugins {
    ...
    id('com.datadoghq.dd-sdk-android-gradle-plugin') version '1.8.0'
}
...
datadog {
    site = 'EU'
}
...
dependencies {
  implementation 'com.datadoghq:dd-sdk-android:1.18.0'
  ...
}

Create or modify a gradle.properties file in your app module with the following values:

DD_API_KEY=value-obtained-at-step-1
DATADOG_API_HOST=api.datadoghq.eu
DATADOG_SITE=datadoghq.eu

11. Exclude Unnecessary Native Library Architectures

The SDK is compiled with a set of native libraries for various architectures such as: armeabi-v7a, arm64-v8a, x86 and x86_64.

In practice it is very unlikely that the x86 and x86_64 ABIs are needed as the vast majority of modern mobile devices nowadays use either armeabi-v7a or arm64-v8a.These binaries are however needed when debugging your application on Android emulators.

In order to exclude these binaries from release builds which will run on real devices, and to considerably decrease the size of the final APK, add the following statements to your app build.gradle file:

android {  
    ...  
    buildTypes {  
        release {  
            ...  
            ndk {  
                abiFilters "armeabi-v7a", "arm64-v8a"  
            }  
        }  
    }  
}

12. Activate The Keyboard

In order to start using the keyboard the users need to go through the process of activation.

In order to launch activation, use the following code:

ActivationExtensions.launchActivationIfNeeded()

The above call launches the activation flow if the keyboard isn't activated.

It is possible to check the keyboard activation state as follows:

// Whether the keyboard is enabled in system settings
val enabled = ActivationExtensions.state.enabled

// Whether the keyboard is switched on as the current keyboard
val current = ActivationExtensions.state.current

🚧

Handling Dependency Conflicts

When integrating Tappa Keyboard SDK into your Android application, you may encounter dependency conflicts, particularly if your app uses similar libraries or components as our SDK. These conflicts often arise due to mismatched versions of shared dependencies, like Firebase or Google Play Services.

Common Conflict Scenarios:

Duplicate Class Errors: This occurs when the same class is found in multiple dependencies, often due to version mismatches. Example error: Execution failed for task ':app:checkDebugDuplicateClasses'.

Failed to Resolve Dependency: This happens when Gradle cannot find a required dependency or a specific version of it. Example error: Could not find com.google.firebase:firebase-analytics-ktx:.

Recommended Solutions:###

1. Updating Dependency Versions in the Main App:
   • Ensure that all common dependencies (e.g., Firebase, Google Play Services) are up to date in your app's build.gradle files.
   • Match the versions of these dependencies with those used in Tappa Keyboard SDK.
2. Excluding Conflicting Dependencies from the SDK:
   • If updating dependencies in your app isn't feasible, you can exclude specific conflicting dependencies from Tappa Keyboard SDK in your app's build.gradle:
   • gradle

     implementation('com.mocha.keyboard:keyboard-sdk:$SDK_VERSION') {  
         exclude group: 'com.google.firebase', module: 'firebase-analytics'  
         // Add more exclusions as necessary  
     }
     

3. Using Gradle's Resolution Strategy:
   • In cases where version conflicts persist, you can force a specific version of a library in your app's build.gradle:
   • gradle

     configurations.all {  
         resolutionStrategy.force 'com.google.android.gms:play-services-measurement-base:version'  
         // Add more forced resolutions as necessary  
     }