MetricSDK Documentation

Overview

MetricSDK is a React Native library designed to facilitate token-based identity verification through the Metric Africa service. The SDK provides methods to initiate token verification and check the status of a verification token, as well as a Verification modal for displaying the verification process.

Moved from react-native-metric-sdk. This package is the continuation of react-native-metric-sdk, which is no longer maintained because the publishing account behind it is inaccessible. The public API is identical — see Migrating from react-native-metric-sdk.

Installation

npm install react-native-metric-sdk-v2
# or
yarn add react-native-metric-sdk-v2

Migrating from react-native-metric-sdk

If you already use react-native-metric-sdk, you do not need to touch your source code. Alias the old name to this package in your package.json:

{
  "dependencies": {
    "react-native-metric-sdk": "npm:react-native-metric-sdk-v2@^0.3.3"
  }
}

Then reinstall and commit your lockfile:

npm install   # or: yarn install

Every existing import ... from 'react-native-metric-sdk' keeps working, types included — the alias installs this package's contents into the node_modules/react-native-metric-sdk/ folder. Supported by npm, Yarn (v1 and Berry) and pnpm.

Do I need to rebuild the native app?

No. This package contains no native code — no podspec, no autolinked modules — so there is no pod install and no Xcode rebuild. The 0.3.3 change is pure JavaScript.

You do need to ship a new JS bundle:

| Your setup | What to do | | --- | --- | | expo-updates or CodePush | Publish an OTA update. No App Store submission required. | | No OTA mechanism | Include it in your next release build. |

What changed in 0.3.3

Two iOS-only WebView flags, to stop the camera step from breaking out into a fullscreen player:

<WebView
  allowsInlineMediaPlayback={true}
  mediaPlaybackRequiresUserAction={false}
  ...
/>

Android behaviour is unaffected. There are no API or breaking changes of any kind.

Prefer to migrate properly?

Drop the alias, depend on react-native-metric-sdk-v2 directly, and update your import paths. The alias exists so you can take the fix immediately and do the rename on your own schedule.

Features

• Token Verification: Initiate token-based verification processes with configurable parameters.
• Token Status Check: Retrieve the status of verification tokens.
• Verification Modal: Seamless integration with a modal for user interactions.

Prerequisite

You should have the react-native-webview package already installed, and have the camera permissions setup for the application. You can do that in the app.json file:

for IOS:

{
  "ios": {
    ...
    "infoPlist": {
      "NSCameraUsageDescription": "To allow Metric Example App access your camera in order to verify your identity."
    }
  },
}

for Android:

{
  "android": {
    ...
    "permissions": ["android.permission.CAMERA"]
  },
}

Usage

For a full example on how to use the package, check the App.tsx file in the example directory.

Initialization

To use the SDK, initialize it with your client ID and secret key:

import MetricSDK from 'react-native-metric-sdk-v2';

const metric = new MetricSDK({
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

Methods

initiateTokenVerification

Initiates the token verification process.

Parameters:

• token (string): Required token for verification.
• onModalClose ((data: VerificationData) => void): Callback executed with the result of the verification when the modal is closed.

Returns:

• An object containing a JSX.Element.

Example:

const { VerificationModal } = await metric.initiateTokenVerification(
  token,
  (data) => {
    if (data) {
      console.log('Verification completed:', data);
    }
  }
);

checkTokenStatus

Checks the status of a verification token.

Parameters:

• token (string): The verification token.

Returns:

• A Promise<string> containing the token status message.

Example:

const status = await metric.checkTokenStatus('your-token');
console.log('Token status:', status);

Example

Below is a complete example of using the SDK in a React Native application:

Example:

import { useState } from "react";
import { View, Button, Text, TextInput } from "react-native";
import MetricSDK, { type VerificationData } from "react-native-metric-sdk-v2";

const metric = new MetricSDK({
  clientId: "your-client-id",
  secretKey: "your-secret-key",
});

const App = () => {
  const [modalComponent, setModalComponent] = useState<JSX.Element | null>(null);
  const [token, setToken] = useState("");
  const [userData, setUserData] = useState<VerificationData>();

  const handleVerifyToken = async () => {
    try {
      const { VerificationModal } = await metric.initiateTokenVerification(
        token,
        (data) => {
          if (data) {
            setUserData(data);
            setModalComponent(null);
          }
        } // Callback to close the modal
      );

      setModalComponent(VerificationModal);
    } catch (err) {
      console.error("Error:", err instanceof Error ? err.message : err);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <View style={{}}>
        <Text>Token:</Text>
        <TextInput
          style={{
            width: 200,
            height: 40,
            paddingHorizontal: 8,
            borderColor: "#000",
            borderWidth: 1.5,
          }}
          value={token}
          onChangeText={setToken}
        />
      </View>
      <Button title="Verify Token" onPress={handleVerifyToken} />
      {userData && (
        <>
          <Text>name: {userData?.customer_name}</Text>
          <Text>sid: {userData?.suid}</Text>
        </>
      )}
      {modalComponent}
    </View>
  );
};

export default App;

API Reference

MetricSDKConfig

The configuration options used to initialize the MetricSDK.

| Property | Type | Description | | ----------- | -------- | ----------------------- | | clientId | string | Your Metric client ID. | | secretKey | string | Your Metric secret key. |

initiateTokenVerification

Starts a verification process and returns a React.JSX.Element component for user interaction.

async initiateTokenVerification(
token: string,
onModalClose: (data: VerificationData | null) => void
): Promise<{ VerificationModal: JSX.Element }>

| Parameter | Type | Description | | -------------- | ------------------------------------------ | ----------------------------------------- | | token | string | The verification token. | | onModalClose | (data: VerificationData \| null) => void | Callback triggered when the modal closes. |

Returns:
An object containing a React.JSX.Element component to be rendered in your application.

checkTokenStatus

Fetches the status of a verification token.

async checkTokenStatus(token: string): Promise<string>

| Parameter | Type | Description | | --------- | -------- | ----------------------- | | token | string | The verification token. |

Returns:
A string representing the status of the token.

VerificationData

The structure of the status object returned after a successful token verification.

| Property | Type | Description | | --------------- | -------- | ------------------------------------ | | status | string | The status of a the verification | | suid | string | the short guid for the verification. | | customer_name | string | The name of the verified customer. |

Error Handling

All methods in the MetricSDK throw errors when something goes wrong. Errors are instances of the MetricSDKError class, which extends the built-in Error class.

Example:

try {
  const status = await metric.checkTokenStatus('your-token');
} catch (error) {
  if (error instanceof MetricSDKError) {
    console.error('Metric SDK Error:', error.message);
  } else {
    console.error('Unexpected Error:', error);
  }
}

Note: Ensure valid tokens and configurations are provided to avoid errors and ensure smooth operation.