Mobile SDK & plugins

Quick links

GitHub · niv2fa-sdk Standalone Agent APK REST API docs

• Platform matrix
• How it works
• Shared methods & result
• Permissions (Allow — SDK reads SIMs)
• Android (Java/Kotlin)
• iOS (Swift)
• Capacitor / Ionic
• Cordova
• Flutter
• React Native
• Adjustment & troubleshooting

Platform matrix

No manual SIM entry. The SDK reads device lines after the user Allows access. Android: SIM chip + saved contacts. iOS: Contacts Me card + saved "my number" contacts. Any matching line → success.

How it works

1. Your backend calls POST /secure-api/v1/verifications with the claimed phone + projectId.
2. API returns verifyUrl (and QR).
3. Your app calls openVerify({ url }) (SDK WebView / Agent).
4. User Allows permission — SDK reads device line(s) (SIM and/or Contacts — never typed by the user).
5. If any reported line matches the registered number → matched: true + webhook identity.verified.
6. SDK returns success to your app UI.

Shared methods & result

{
  "matched": true,
  "status": "completed",
  "matchedSlot": "sim1",
  "sessionId": "sess_…",
  "platform": "android" | "ios"
}

Always treat the webhook as the source of truth for your backend.

Permissions (Allow — SDK reads SIMs)

Android: READ_PHONE_STATE, READ_PHONE_NUMBERS, READ_CONTACTS, CAMERA, INTERNET, ACCESS_NETWORK_STATE. Reads SIM1/SIM2; also scans saved contacts named e.g. My number or رقمي if SIM MSISDN is blank.

iOS: Contacts permission → read My Card (Me) plus saved owner contacts (same naming patterns) → compare to session. Not SIM chip. No background calls. Add NSContactsUsageDescription in Info.plist.

Chrome / plain browser cannot read SIMs — open verifyUrl inside the SDK or Agent only.

Android (Java / Kotlin)

Docs: ANDROID.md · Module: android/

git clone https://github.com/kreatedeviq/niv2fa-sdk.git

# settings.gradle
include ':niv2fa-sdk'
project(':niv2fa-sdk').projectDir = new File('path/to/niv2fa-sdk/android')

# app/build.gradle
implementation project(':niv2fa-sdk')

Niv2faSdk.requestPermissions(this)
startActivityForResult(Niv2faSdk.verifyIntent(this, sessionUrl), 9101)
// onActivityResult → Niv2faSdk.parseResult(data)

iOS (Swift)

Docs: IOS.md · Package: ios/ (SPM)

.package(url: "https://github.com/kreatedeviq/niv2fa-sdk.git", from: "1.0.0")
// product: Niv2faSdk

Niv2faSdk.openVerify(from: self, sessionUrl: url) { result in
  // result.matched — no manual SIM typing
}

Same product rule: SDK bridge only. For dual-SIM chip MSISDN, Android SDK / Agent is the reliable path (Apple limits silent MSISDN).

Capacitor / Ionic Capacitor

Docs: CAPACITOR.md · Android + iOS

npm i https://github.com/kreatedeviq/niv2fa-sdk/packages/capacitor
npx cap sync

import Niv2fa from '@niv2fa/capacitor'
await Niv2fa.requestPermissions()
const r = await Niv2fa.openVerify({ url: verifyUrl }) // SDK reads SIMs → match

Cordova / Ionic Cordova

Docs: CORDOVA.md · Android + iOS

cordova plugin add https://github.com/kreatedeviq/niv2fa-sdk.git#main:packages/cordova

Niv2fa.requestPermissions(console.log, console.error)
Niv2fa.openVerify({ url: verifyUrl }, console.log, console.error)

Flutter

Docs: FLUTTER.md · Android + iOS

dependencies:
  niv2fa_flutter:
    git:
      url: https://github.com/kreatedeviq/niv2fa-sdk.git
      path: packages/flutter

await Niv2faFlutter.requestPermissions();
final r = await Niv2faFlutter.openVerify(verifyUrl);

React Native

Docs: REACT_NATIVE.md · Android + iOS

import { openVerify, requestPermissions } from '@niv2fa/react-native'
await requestPermissions()
const r = await openVerify(verifyUrl)

Adjustment & making it work

1. Set project webhook_url in the dashboard.
2. Create session with the exact phone the user claims (E.164).
3. Open verifyUrl via openVerify in the SDK (not Chrome).
4. User Allows Phone — SDK reads SIM1/SIM2 automatically.
5. Match → success response to the app + webhook identity.verified.

Common issues

Clone

git clone https://github.com/kreatedeviq/niv2fa-sdk.git
cd niv2fa-sdk
# Guides: docs/ANDROID.md · IOS.md · CAPACITOR.md · CORDOVA.md · FLUTTER.md · REACT_NATIVE.md