React Native quickstart

Five minutes. One package, two credential files, one function call.

Before you start

Your Android build targets minSdk 24 and uses JDK 17.

Your iOS build targets iOS 13.0 or later.

You have your three credentials. See Get your keys.

Step 1: install the package

Use yarn add @callerapi/react-native if you use Yarn.

Autolinking connects the native code on both platforms, so you edit no Xcode project settings and no Gradle files.

Step 2: add your Android credentials

Open android/app/src/main/AndroidManifest.xml. Paste these three entries inside the <application> tag:

<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>

Step 3: add your iOS credentials

Open ios/YourApp/Info.plist. Paste these four lines before the closing </dict>:

<key>CallerAPISDKKey</key>
<string>paste-your-sdk-key</string>
<key>CallerAPISDKSecret</key>
<string>paste-your-sdk-secret</string>

Run cd ios && pod install && cd .. again after editing.

Skip this step if you only build for Android today. iOS lookups fail without it, and they fail quietly.

Step 4: look up a number

import CallerAPI from '@callerapi/react-native';

const label = await CallerAPI.lookupLabel('+18883578668');
console.log(`Caller: ${label ?? 'Unknown'}`);

Rebuild the app with npx react-native run-android or npx react-native run-ios. The Metro console prints Caller: CallerAPI LC.

The import is a default import. import CallerAPI from '...' is correct. import { CallerAPI } from '...' is not, and it gives you undefined.

There is no initialize call. The native module starts the SDK when React Native loads it, and reads your credentials from the two files above.

That is the quickstart. Go to Check it works.

Checking for spam

if (await CallerAPI.isSpam('+19999999999')) {
  // show a warning in your own UI
}

A complete example

import React, { useEffect, useState } from 'react';
import { Text } from 'react-native';
import CallerAPI from '@callerapi/react-native';

export function CallerName({ phone }: { phone: string }) {
  const [name, setName] = useState('Checking...');

  useEffect(() => {
    let cancelled = false;
    CallerAPI.lookupLabel(phone)
      .then((label) => {
        if (!cancelled) setName(label ?? 'Unknown caller');
      })
      .catch(() => {
        if (!cancelled) setName('Unknown caller');
      });
    return () => {
      cancelled = true;
    };
  }, [phone]);

  return <Text>{name}</Text>;
}

Things that will confuse you

"CallerAPI native module is not available". The native side is not linked. Stop Metro, run pod install for iOS, then rebuild the app. A reload is not enough, because adding native code needs a full build.

It works on Android and returns null on iOS. You skipped step 3, or you did not run pod install after editing Info.plist.

CallerAPI.lookupLabel is not a function. You used a named import. Change it to a default import.

The Android build fails on Gradle. Confirm JDK 17 with java -version.

Which functions exist on which platform

Some functions only make sense on one platform. They return false rather than throwing on the other, so it is safe to call them without a Platform.OS check.

Function	Android	iOS
`lookupLabel`, `isSpam`, `checkIn`	Yes	Yes
`requestCallScreeningRole`, `isCallScreeningRoleGranted`	Yes	Returns false
`requestOverlayPermission`, `isOverlayPermissionGranted`	Yes	Returns false
`bootstrapFromInfoPlist`, `getLiveLookupStatus`, `prewarmLiveLookup`	Returns false	Yes
`setAnalyticsConsent`	Yes	Does nothing

setFeatureEnabled and setAnalyticsConsent return nothing. Do not await them.

Check it works

Block and name calls on Android

Name callers on the iOS call screen

All methods

React Native

React Native quickstart#

Before you start#

Step 1: install the package#

Step 2: add your Android credentials#

Step 3: add your iOS credentials#

Step 4: look up a number#

Checking for spam#

A complete example#

Things that will confuse you#

Which functions exist on which platform#

Next#