Android

Five minutes. Four edits to your project.

Before you start

Your app targets Android 7.0 or later (minSdk 24).

Your machine builds with JDK 17.

You have your three credentials. See Get your keys.

Step 1: add the dependency

Open app/build.gradle.kts. Add one line inside dependencies:

The SDK is on Maven Central, so you do not add a repository. Confirm that mavenCentral() and google() are already in your settings.gradle.kts, because almost every Android project has both.

If you use Groovy, the line is the same without the brackets:

Click Sync Now in the bar at the top of Android Studio.

Step 2: add your credentials

Open app/src/main/AndroidManifest.xml. Paste these three entries inside the <application> tag, next to your activities:

<application ... >

    <meta-data android:name="com.callerapi.sdk.CLIENT_KEY"
               android:value="paste-your-client-key" />
    <meta-data android:name="com.callerapi.sdk.SDK_KEY"
               android:value="paste-your-sdk-key" />
    <meta-data android:name="com.callerapi.sdk.SDK_SECRET"
               android:value="paste-your-sdk-secret" />

</application>

A common mistake is pasting these outside <application>. The build still succeeds, and the SDK then finds no credentials at run time.

Step 3: start the SDK

The SDK needs to start once, when your app process starts.

If you already have an Application subclass, add the marked line to it. If you do not, create this file at app/src/main/java/com/yourcompany/yourapp/App.kt:

Now tell Android to use it. In the same manifest, add android:name to the <application> tag:

<application
    android:name=".App"
    ... >

register reads the credentials from the manifest, so you pass nothing but the context. It returns immediately and does the slow work on a background thread.

Step 4: look up a number

lookupLabel is a suspend function, so call it from a coroutine. From an activity or fragment, lifecycleScope is the easiest:

Run the app. Logcat prints Caller: CallerAPI LC.

That is the quickstart. Go to Check it works to confirm the dashboard sees your app.

Checking for spam

isSpam answers whether a number is a known spam caller:

isSpam blocks the thread it runs on. Keep it inside a coroutine, or on a background thread. Never call it on the main thread, and never call it from a call screening callback. Android call screening explains what to use on the call path instead.

Things that will confuse you

lookupLabel returned null. Either the number does not belong to a business, which is the normal case, or the lookup failed. The function cannot tell you which. Use lookupLabelCode when you need the difference. See Errors.

The app crashed with "CallerAPI not initialised". You called a lookup before register. Check that your manifest has android:name=".App" and that the class name matches your file.

Every lookup fails. Your credentials are missing or wrong. Filter Logcat for CallerAPI and look for native init failed. The SDK logs the failure and then stays off, so nothing else tells you.

Move your credentials out of the manifest

Before you ship, keep the secret out of git. Put it in local.properties, which git already ignores:

Read it in app/build.gradle.kts:

Then reference the placeholders in the manifest:

<meta-data android:name="com.callerapi.sdk.CLIENT_KEY"
           android:value="${callerApiClientKey}" />
<meta-data android:name="com.callerapi.sdk.SDK_KEY"
           android:value="${callerApiSdkKey}" />
<meta-data android:name="com.callerapi.sdk.SDK_SECRET"
           android:value="${callerApiSdkSecret}" />

Your build server needs the same three values as environment variables.

Check it works

Android call screening

Methods

Before you start#

Step 1: add the dependency#

Step 2: add your credentials#

Step 3: start the SDK#

Step 4: look up a number#

Checking for spam#

Things that will confuse you#

Move your credentials out of the manifest#

Next#