VTV ID SDK for React Native

Introduction

VTV ID SDK is the official authentication library for React Native, providing secure login with OAuth 2.0 + PKCE.

Features

• OAuth 2.0 + PKCE - Secure authentication following international standards
• Chrome Custom Tabs / Safari - Smooth in-app login experience
• Secure Storage - Token storage with iOS Keychain / Android Keystore
• Auto Token Refresh - No manual intervention needed
• Profile Management - Full user information
• React Hooks - Modern API with hooks

Note: This SDK only supports Bare React Native (Expo managed workflow is not supported).

Requirements

| Requirement | Version | | ------------------ | ------------------ | | React Native | 0.68+ | | React | 17.0+ | | Node.js | 16.0+ | | iOS Deployment | 13.0+ | | Android SDK | 24+ (Android 7.0+) |

Installation

Step 1: Install SDK and dependencies

npm install @vtv-id/react-native-vtv-id react-native-keychain

react-native-keychain is a required native module for secure token storage (iOS Keychain / Android Keystore).

iOS:

cd ios && pod install && cd ..

Android:

No additional steps required. Autolinking handles everything.

Step 2: Native Configuration

iOS - ios/YourApp/Info.plist

Add URL Scheme for OAuth callback:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>vn.vtv.id</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>vtvid</string>
        </array>
    </dict>
</array>

Android - android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders = [
            appAuthRedirectScheme: "vtvid"
        ]
    }
}

Android - android/app/src/main/AndroidManifest.xml

Add deep link intent-filter to MainActivity:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="vtvid" />
</intent-filter>

SDK Configuration

Initialize the SDK once at app startup:

import VtvId, { Environment, LogLevel } from '@vtv-id/react-native-vtv-id';

await VtvId.initialize({
  appClientId: 'your-app-client-id',        // From VTV Admin Portal
  appClientSecret: 'your-app-client-secret', // From VTV Admin Portal
  redirectUri: 'vtvid://callback',
  environment: Environment.PRODUCTION,
  logLevel: LogLevel.NONE,
});

Parameters

| Parameter | Required | Description | | ---------------- | -------- | ----------------------------------------------------- | | appClientId | No | External app client ID from VTV Admin Portal | | appClientSecret| No | External app client secret from VTV Admin Portal | | redirectUri | No | OAuth redirect URI (default: vtvid://callback) | | environment | No | Environment (default: PRODUCTION) | | baseUrl | No | Custom base URL (overrides environment URL) | | logLevel | No | Log level (default: NONE) | | scopes | No | OAuth scopes (default: ["openid","profile","email"]) |

Environments

| Environment | URL | | ------------- | ---------------------------------- | | PRODUCTION | https://id.vtv.vn/api/v1 | | STAGING | https://id-staging.vtv.vn/api/v1| | DEVELOPMENT | https://id-dev.vtv.vn/api/v1 | | LOCAL | http://localhost:8080/api/v1 |

Usage

Login

import { useVtvAuth, IdentityProvider } from '@vtv-id/react-native-vtv-id';

const LoginScreen = () => {
  const { login, isLoading, error } = useVtvAuth();

  const handleLogin = async () => {
    try {
      const user = await login(IdentityProvider.VTV_ID);
      console.log('Login successful:', user.fullName);
    } catch (err) {
      console.error('Login failed:', err);
    }
  };

  return <Button title="Login" onPress={handleLogin} disabled={isLoading} />;
};

Identity Providers

| Provider | Value | | ---------------- | --------------------------- | | VTV ID | IdentityProvider.VTV_ID | | Google | IdentityProvider.GOOGLE | | Facebook | IdentityProvider.FACEBOOK | | Apple | IdentityProvider.APPLE | | VNeID | IdentityProvider.VNEID |

User State

import { useUser } from '@vtv-id/react-native-vtv-id';

const ProfileScreen = () => {
  const user = useUser();

  if (!user) return <Text>Please login</Text>;

  return (
    <View>
      <Text>{user.fullName}</Text>
      <Text>{user.email}</Text>
    </View>
  );
};

Profile Management

import { useVtvProfile } from '@vtv-id/react-native-vtv-id';

const { getProfile, updateProfile, isLoading } = useVtvProfile();

// Fetch profile
const profile = await getProfile();

// Update profile
await updateProfile({ firstName: 'John', lastName: 'Doe' });

Logout

import { useVtvAuth } from '@vtv-id/react-native-vtv-id';

const { logout } = useVtvAuth();
await logout();

Direct Usage (without Hooks)

import VtvId, { IdentityProvider } from '@vtv-id/react-native-vtv-id';

const user = await VtvId.login(IdentityProvider.VTV_ID);
const isAuth = VtvId.isAuthenticated();
const token = await VtvId.getAccessToken();
await VtvId.logout();

API Reference

VtvIdConfig

interface VtvIdConfig {
  appClientId?: string;
  appClientSecret?: string;
  redirectUri?: string;
  environment?: Environment;
  baseUrl?: string;
  logLevel?: LogLevel;
  scopes?: string[];
}

VtvUser

interface VtvUser {
  id: string;
  email?: string;
  emailVerified: boolean;
  phone?: string;
  phoneVerified: boolean;
  firstName?: string;
  lastName?: string;
  fullName?: string;
  avatar?: string;
  dateOfBirth?: string;
  gender?: Gender;
  address?: Address;
  metadata?: Record<string, string>;
}

Hooks

| Hook | Description | | ---------------------- | ---------------------------- | | useVtvAuth() | Login, logout, loading, error| | useUser() | Current user info | | useVtvProfile() | Get/update profile | | useIsAuthenticated() | Boolean auth status | | useAccessToken() | Get access token |

Troubleshooting

Module not found

npm install @vtv-id/react-native-vtv-id
npx react-native start --reset-cache

Deep link not working

• iOS: Verify Info.plist has URL Scheme vtvid
• Android: Verify manifestPlaceholders and intent-filter

iOS build errors

cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

Android build errors

cd android && ./gradlew clean && cd ..

License

MIT - Copyright 2026 AIPOWER. All rights reserved.