vc-cdp-rn-sdk 0.1.1 → 0.1.2

package/README.md

@@ -10,24 +10,28 @@ CDP SDK cho React Native — tracking events và user profiles cho hệ thống
 - [Khởi tạo](#khởi-tạo)
 - [Luồng hoạt động](#luồng-hoạt-động)
 - [User / Profile](#user--profile)
-  - [Đăng nhập](#đăng-nhập-identifyuser)
-  - [Cập nhật profile](#cập-nhật-profile-updateprofile)
-  - [Lấy thông tin profile](#lấy-thông-tin-profile-getprofile)
-  - [Trait setters](#trait-setters-chainable)
+  - [identifyUser](#identifyuser--đăng-nhập)
+  - [Trait Setters](#trait-setters--cập-nhật-từng-thuộc-tính)
+  - [updateProfile](#updateprofile--force-update)
+  - [getProfile](#getprofile--lấy-thông-tin-profile)
   - [Consents](#consents)
   - [Scores](#scores)
   - [Products](#products)
-  - [Metadata](#metadata)
-  - [Campaign / UTM](#campaign--utm)
-  - [Push Token](#push-token)
-  - [Đăng xuất](#đăng-xuất)
+  - [Metadata, Campaign, Push Token](#metadata-campaign-push-token)
+  - [getUserIdentities](#getuseridentities)
+  - [destroy_session](#destroy_session--đăng-xuất)
 - [Event Tracking](#event-tracking)
-  - [Track sự kiện](#track-sự-kiện)
-  - [Track màn hình](#track-màn-hình-screen)
-  - [Flush thủ công](#flush-thủ-công)
-- [Lấy thông tin định danh](#lấy-thông-tin-định-danh)
+  - [track](#track--custom-event)
+  - [screen](#screen--màn-hình)
+  - [React Navigation](#tích-hợp-react-navigation)
+  - [Batch Processing](#batch-processing)
+  - [flush](#flush--gửi-ngay)
+  - [destroy](#destroy--dọn-dẹp)
 - [Bảo mật](#bảo-mật)
-- [Dependencies](#dependencies)
+  - [HMAC-SHA256](#hmac-sha256-signature)
+  - [AES-256-CBC](#aes-256-cbc-encryption)
+  - [Best Practices](#best-practices)
+- [Tích hợp React Navigation đầy đủ](#tích-hợp-react-navigation-đầy-đủ)
 - [API Reference](#api-reference)
 
 ---
@@ -35,49 +39,92 @@ CDP SDK cho React Native — tracking events và user profiles cho hệ thống
 ## Cài đặt
 
 ```bash
-npm install vc-cdp-rn-sdk @react-native-async-storage/async-storage react-native-device-info crypto-js
+npm install vc-cdp-rn-sdk
 ```
 
-### iOS
+### Peer Dependencies
+
+```bash
+npm install @react-native-async-storage/async-storage
+npm install react-native-device-info
+```
+
+#### iOS
 
 ```bash
 cd ios && pod install
 ```
 
-### Android
+#### Android
 
-Không cần bước cấu hình thêm.
+Không cần thêm cấu hình nếu dùng React Native >= 0.68 (auto-linking).
 
 ---
 
 ## Khởi tạo
 
-Gọi `CdpRnSdk.create()` **một lần duy nhất** tại entry point của app (ví dụ `App.tsx`). SDK dùng `AsyncStorage` nên init là bất đồng bộ.
+Khởi tạo SDK **một lần duy nhất** tại entry point của app. SDK dùng `AsyncStorage` nên init là **async**.
 
 ```typescript
+// src/lib/cdp.ts
 import { CdpRnSdk } from 'vc-cdp-rn-sdk';
 
-let cdp: CdpRnSdk;
-
-export async function setupCdp() {
-  cdp = await CdpRnSdk.create({
-    apiKey: 'YOUR_API_KEY',       // Bắt buộc — do CDP cấp
-    secretKey: 'YOUR_SECRET_KEY', // Bắt buộc — dùng ký HMAC + mã hoá AES
-    source: 'DOP',                // Bắt buộc — kênh phát triển (khai báo với CDP trước)
-    serviceName: 'DOP',           // Bắt buộc — DOP | LOS | LMS
-
-    // Tuỳ chọn
-    baseUrl: 'https://stg-ingestlog.vietcredit.com.vn', // mặc định: staging
-    isTest: true,          // đánh dấu môi trường test
-    debug: true,           // in log ra console
-    batchSize: 10,         // gửi batch khi queue đủ n events (mặc định: 10)
-    batchInterval: 5000,   // hoặc sau n ms dù chưa đủ batch (mặc định: 5000)
-    enableEncryption: true // mã hoá PII bằng AES-256-CBC (mặc định: true)
+let _cdp: CdpRnSdk | null = null;
+
+export async function initCdp(): Promise<CdpRnSdk> {
+  _cdp = await CdpRnSdk.create({
+    apiKey:     'YOUR_API_KEY',
+    secretKey:  'YOUR_SECRET_KEY',
+    source:     'DOP',
+    serviceName: 'VC_APP',
+    baseUrl:    'https://ingestlog.vietcredit.com.vn',
+    debug:      __DEV__,
   });
+  return _cdp;
+}
+
+export function getCdp(): CdpRnSdk {
+  if (!_cdp) throw new Error('CDP SDK chưa được khởi tạo. Gọi initCdp() trước.');
+  return _cdp;
 }
 ```
 
-> **Lưu ý:** Các events được gọi trước khi `create()` hoàn thành sẽ được buffer lại và tự động gửi sau khi khởi tạo xong — không bị mất.
+```typescript
+// App.tsx
+import { useEffect } from 'react';
+import { initCdp } from './lib/cdp';
+
+export default function App() {
+  useEffect(() => {
+    initCdp();
+  }, []);
+  // ...
+}
+```
+
+> **Lưu ý:** Mỗi lần `CdpRnSdk.create()` được gọi, SDK tự động tạo `session_id` mới — tương ứng với 1 lần mở app.
+
+### Cấu hình đầy đủ
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|---|---|---|---|
+| `apiKey` | `string` | — | **Bắt buộc.** API Key do CDP cấp |
+| `secretKey` | `string` | — | **Bắt buộc.** Secret Key để ký HMAC và mã hoá AES |
+| `source` | `string` | — | **Bắt buộc.** Kênh tích hợp (khai báo với CDP trước) |
+| `serviceName` | `string` | — | **Bắt buộc.** `VC_APP` \| `DOP` \| `LOS` \| `LMS` |
+| `baseUrl` | `string` | Staging URL | URL API CDP (không có `/v1`) |
+| `isTest` | `boolean` | `false` | Đánh dấu môi trường test |
+| `debug` | `boolean` | `false` | In log ra console |
+| `batchSize` | `number` | `10` | Số events tối đa trong 1 batch |
+| `batchInterval` | `number` | `5000` | Thời gian (ms) giữa các lần flush tự động |
+| `enableEncryption` | `boolean` | `true` | Mã hoá PII bằng AES-256-CBC |
+
+### Môi trường
+
+| Môi trường | baseUrl |
+|---|---|
+| Staging | `https://stg-ingestlog.vietcredit.com.vn` |
+| Production | `https://ingestlog.vietcredit.com.vn` |
 
 ---
 
@@ -85,113 +132,77 @@ export async function setupCdp() {
 
 ```
 App khởi động
-  └─> CdpRnSdk.create(config)
-        │  - Tạo session_id mới (luôn fresh mỗi lần mở app)
-        │  - Load anonymous_id, device_id từ AsyncStorage (persistent)
-        │  - Load profile_id từ AsyncStorage (nếu đã login trước đó)
-        │  - Thu thập device info (brand, model, OS)
+  └─> CdpRnSdk.create(config)   ← async
+        │  - Load/tạo device_id    → AsyncStorage (persist vĩnh viễn)
+        │  - Load/tạo anonymous_id → AsyncStorage (persist vĩnh viễn)
+        │  - Tạo session_id mới    → AsyncStorage (mỗi lần mở app)
+        │  - Load profile_id       → AsyncStorage (nếu đã login)
         │
         ├─ User CHƯA login
-        │     └─> cdp.track(event)
+        │     └─> cdp.track() / cdp.screen()
         │           profile_id = null, gắn anonymous_id + device_id + session_id
-        │           CDP sẽ identity-resolve khi user login sau
         │
         └─ User login
               └─> cdp.identifyUser(userId, traits)
                     └─> POST /v1/profiles/track → nhận profile_id
-                          └─> cdp.track(event)
-                                profile_id được gắn vào mọi event tiếp theo
+                          └─> cdp.track() gắn profile_id vào mọi event
 ```
 
-**Session ID:** Mỗi lần mở app tạo một `session_id` mới. `device_id` và `anonymous_id` được giữ nguyên giữa các lần mở.
+**Storage scope (AsyncStorage):**
+
+| | Vòng đời |
+|---|---|
+| `device_id` | Vĩnh viễn (đến khi xoá app) |
+| `anonymous_id` | Vĩnh viễn (rotate khi logout) |
+| `session_id` | Tạo mới mỗi lần `create()` |
+| `profile_id` | Xoá khi `destroy_session()` |
 
 ---
 
 ## User / Profile
 
-### Đăng nhập (`identifyUser`)
-
-Gọi sau khi user đăng nhập thành công. SDK sẽ gọi `POST /v1/profiles/track`, nhận `profile_id` từ CDP và lưu vào storage để dùng cho các lần sau.
+### identifyUser — Đăng nhập
 
 ```typescript
-await cdp.identifyUser('user_123', {
-  phone: '0901234567',
-  full_name: 'Nguyễn Văn A',
-  email: 'user@example.com',
-  gender: 'M',        // 'M' | 'F' | 'O'
-  dob: '1990-01-15',  // yyyy-MM-dd
-});
-
-// Tài khoản tổ chức (doanh nghiệp)
-await cdp.identifyUser('org_456', { full_name: 'Công ty ABC' }, 'ORG');
-
-// Alias ngắn gọn
-await cdp.identify('user_123', { phone: '0901234567' });
+await cdp.identifyUser(userId, traits?, partyType?)
 ```
 
 | Tham số | Kiểu | Bắt buộc | Mô tả |
 |---|---|---|---|
-| `userId` | `string` | ✓ | Mã user trong hệ thống |
+| `userId` | `string` | ✓ | Mã user trong hệ thống nội bộ |
 | `traits` | `UserTraits` | | Thông tin nhân khẩu học |
 | `partyType` | `'PERSON' \| 'ORG'` | | Mặc định `'PERSON'` |
 
----
-
-### Cập nhật profile (`updateProfile`)
-
-Force-update profile theo `profile_id` — không trigger identity resolution. Dùng khi cần cập nhật một số trường cụ thể sau khi đã có `profile_id`.
-
-Gọi `POST /v1/profiles/update`.
-
 ```typescript
-await cdp.updateProfile({
-  traits: {
-    kyc_status: 'verified',
-    mps_verified: true,
-  },
-  consents: [
-    { consent_type: 'marketing_email', status: true, consent_date: '2025-06-01' },
-  ],
+// Cá nhân
+await cdp.identifyUser('user_001', {
+  phone:        '0901234567',
+  email:        'user@example.com',
+  full_name:    'Nguyễn Văn A',
+  gender:       'M',
+  dob:          '1990-01-15',
+  idcard:       '012345678901',
+  address:      '123 Lê Lợi, Q.1, TP.HCM',
+  occupation:   'Kỹ sư phần mềm',
+  nationality:  'Vietnamese',
+  marital_status: 'single',
 });
 
-// Cập nhật profile_id khác (không phải profile hiện tại)
-await cdp.updateProfile({
-  profile_id: 'cdp_profile_xyz',
-  traits: { occupation: 'Kỹ sư' },
-});
-```
-
-| Tham số | Kiểu | Mô tả |
-|---|---|---|
-| `profile_id` | `string` | Mặc định lấy profile_id hiện tại |
-| `traits` | `UserTraits` | Các trường cần update |
-| `consents` | `ConsentInfo[]` | Danh sách consent |
-| `scores` | `ScoreInfo[]` | Danh sách điểm |
-| `products` | `ProductInfo[]` | Danh sách sản phẩm |
-| `metadata` | `object` | Thông tin bổ sung |
-
----
-
-### Lấy thông tin profile (`getProfile`)
-
-Gọi `GET /v1/profiles/get/{profile_id}`.
-
-```typescript
-// Lấy profile hiện tại
-const profile = await cdp.getProfile();
-
-// Hoặc chỉ định profile_id cụ thể
-const profile = await cdp.getProfile('cdp_profile_xyz');
+console.log(cdp.getProfileId()); // → "177671850461184000"
 
-console.log(profile?.traits);
-console.log(profile?.consents);
+// Tổ chức
+await cdp.identifyUser('org_001', {
+  full_name: 'Công ty TNHH ABC',
+  phone:     '0281234567',
+  email:     'contact@abc.vn',
+}, 'ORG');
 ```
 
 ---
 
-### Trait setters (chainable)
+### Trait Setters — Cập nhật từng thuộc tính
 
-Cập nhật từng thuộc tính riêng lẻ. Mỗi setter sẽ tự gọi `POST /v1/profiles/track` với `type: update`. Các setter có thể nối chuỗi.
+Chainable. Mỗi setter gọi ngay `POST /v1/profiles/track` (type: update).
 
 ```typescript
 cdp
@@ -201,352 +212,615 @@ cdp
   .add_email('user@example.com')
   .add_mobile('0901234567')
   .add_gender('M')
-  .add_birthday(new Date('1990-01-15'))    // hoặc '1990-01-15'
+  .add_birthday('1990-01-15')
   .add_idcard('012345678901')
   .add_old_idcard('123456789')
-  .add_address('123 Đường ABC, Hà Nội')
+  .add_address('123 Lê Lợi, Q.1, TP.HCM')
   .add_occupation('Kỹ sư phần mềm')
   .add_nationality('Vietnamese')
   .add_marital_status('single')
   .add_religion('Buddhist')
-  .add_zalo_id('zalo_123')
-  .add_tiktok_id('tiktok_abc');
-
-// Cập nhật nhiều thuộc tính cùng lúc
-cdp.add_user_attributes({
-  occupation: 'Kỹ sư',
-  nationality: 'Vietnamese',
-  mps_verified: true,
-});
-
-// Cập nhật một thuộc tính tùy chỉnh
-cdp.add_user_attribute('custom_field', 'value');
+  .add_zalo_id('zalo_user_001')
+  .add_tiktok_id('tiktok_user_001');
 ```
 
-**Danh sách trait setters:**
-
-| Method | Trường trong `traits` | Ghi chú |
+| Method | Trường | Ghi chú |
 |---|---|---|
 | `add_first_name(v)` | `first_name` | |
 | `add_last_name(v)` | `last_name` | |
 | `add_user_name(v)` | `full_name` | |
-| `add_email(v)` | `email` | PII — tự động mã hoá |
-| `add_mobile(v)` | `phone` | PII — tự động mã hoá |
+| `add_email(v)` | `email` | 🔒 PII |
+| `add_mobile(v)` | `phone` | 🔒 PII |
 | `add_gender(v)` | `gender` | `'M'` \| `'F'` \| `'O'` |
 | `add_birthday(v)` | `dob` | `Date` hoặc `'yyyy-MM-dd'` |
-| `add_idcard(v)` | `idcard` | PII — tự động mã hoá |
-| `add_old_idcard(v)` | `old_idcard` | PII — tự động mã hoá |
-| `add_address(v)` | `address` | PII — tự động mã hoá |
+| `add_idcard(v)` | `idcard` | 🔒 PII |
+| `add_old_idcard(v)` | `old_idcard` | 🔒 PII |
+| `add_address(v)` | `address` | 🔒 PII |
 | `add_occupation(v)` | `occupation` | |
 | `add_nationality(v)` | `nationality` | |
 | `add_marital_status(v)` | `marital_status` | |
-| `add_religion(v)` | `religion` | PII — tự động mã hoá |
+| `add_religion(v)` | `religion` | 🔒 PII |
 | `add_zalo_id(v)` | `zalo_id` | |
 | `add_tiktok_id(v)` | `tiktok_id` | |
-| `add_user_attribute(name, val)` | tùy chỉnh | |
-| `add_user_attributes(obj)` | nhiều trường | |
-| `setUserAttributes(obj)` | nhiều trường | alias |
+| `add_user_attribute(name, val)` | custom | Bất kỳ trường nào |
+| `add_user_attributes(obj)` | nhiều trường | Batch update |
+| `setUserAttributes(obj)` | nhiều trường | Alias |
 
 ---
 
-### Consents
+### updateProfile — Force-update
 
-Lưu danh sách consent của user. Sẽ được đính kèm vào mọi lần gọi profile sau đó.
+```typescript
+await cdp.updateProfile({
+  traits: { kyc_status: 'verified', mps_verified: true },
+  consents: [{ consent_type: 'marketing_sms', status: true, consent_date: '2025-06-01' }],
+});
+```
+
+---
+
+### getProfile — Lấy thông tin profile
+
+```typescript
+const profile = await cdp.getProfile();
+const profile = await cdp.getProfile('cdp_123');
+```
+
+---
+
+### Consents
 
 ```typescript
 cdp.setConsents([
-  {
-    consent_type: 'marketing_sms',
-    status: true,
-    consent_date: '2025-06-01',
-  },
-  {
-    consent_type: 'marketing_email',
-    status: false,
-  },
+  { consent_type: 'marketing_sms',   status: true,  consent_date: '2025-06-01' },
+  { consent_type: 'marketing_email', status: false },
+  { consent_type: 'data_sharing',    status: true },
 ]);
 ```
 
-| Trường | Kiểu | Bắt buộc | Mô tả |
-|---|---|---|---|
-| `consent_type` | `string` | ✓ | Loại consent |
-| `status` | `boolean` | ✓ | `true` = đồng ý |
-| `consent_date` | `string` | | Ngày đồng ý |
-
 ---
 
 ### Scores
 
-Lưu điểm tín dụng / rủi ro của user.
-
 ```typescript
 cdp.setScores([
-  {
-    score_type: 'credit_score',
-    score_value: 720,
-    score_date: '2025-06-01',
-  },
-  {
-    score_type: 'risk_score',
-    score_value: 85,
-  },
+  { score_type: 'credit_score', score_value: 720, score_date: '2025-06-01' },
 ]);
 ```
 
-| Trường | Kiểu | Bắt buộc | Mô tả |
-|---|---|---|---|
-| `score_type` | `string` | ✓ | Loại điểm |
-| `score_value` | `number` | ✓ | Giá trị |
-| `score_date` | `string` | | Ngày tính điểm |
-
 ---
 
 ### Products
 
-Lưu danh sách sản phẩm mà user đang sử dụng.
-
 ```typescript
 cdp.setProducts([
-  {
-    product_code: 'LOAN_CONSUMER',
-    product_name: 'Vay tiêu dùng',
-    status: 'active',
-  },
-  {
-    product_code: 'CREDIT_CARD',
-    product_name: 'Thẻ tín dụng',
-    status: 'pending',
-  },
+  { product_code: 'LOAN_CONSUMER', product_name: 'Vay tiêu dùng', status: 'active' },
 ]);
 ```
 
-| Trường | Kiểu | Bắt buộc | Mô tả |
-|---|---|---|---|
-| `product_code` | `string` | ✓ | Mã sản phẩm |
-| `product_name` | `string` | | Tên sản phẩm |
-| `status` | `string` | | Trạng thái |
-
 ---
 
-### Metadata
-
-Gắn thêm thông tin tùy chỉnh vào tất cả các payload (profile + event).
+### Metadata, Campaign, Push Token
 
 ```typescript
-cdp.setMetadata({
-  schema_version: '2.0',
-  app_flavor: 'production',
-  referral_code: 'REF123',
-});
-```
-
----
-
-### Campaign / UTM
+cdp.setMetadata({ schema_version: '2.0', referral_code: 'REF123' });
 
-Gắn thông tin chiến dịch vào tất cả event và profile call tiếp theo.
-
-```typescript
 cdp.setCampaign({
-  utm_source: 'facebook',
-  utm_medium: 'cpc',
+  utm_source:   'facebook',
+  utm_medium:   'cpc',
   utm_campaign: 'summer_loan_2025',
-  utm_term: 'vay_tieu_dung',
-  utm_content: 'banner_top',
 });
+
+// Push notification token (Expo hoặc FCM)
+cdp.setPushToken('ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]');
+cdp.setPushToken('fcm_token_abc123...');
 ```
 
 ---
 
-### Push Token
-
-Lưu FCM token (Android) hoặc APNs token (iOS) để CDP dùng cho push notification.
+### getUserIdentities
 
 ```typescript
-cdp.setPushToken('FCM_OR_APNS_TOKEN_HERE');
+const ids = cdp.getUserIdentities();
+// {
+//   user_id:      'user_001',
+//   profile_id:   '177671850461184000',
+//   anonymous_id: 'uuid-...',
+//   device_id:    'uuid-...',
+//   session_id:   'uuid-...',
+// }
+
+cdp.getProfileId();
+cdp.getDeviceId();
+cdp.getSessionId();
+cdp.getUserAttribute('phone');
 ```
 
 ---
 
-### Đăng xuất
-
-Gửi event logout, xoá toàn bộ dữ liệu user, rotate `anonymous_id` và `session_id`. `device_id` được giữ lại.
+### destroy_session — Đăng xuất
 
 ```typescript
 await cdp.destroy_session();
-
-// Alias
+// hoặc alias:
 await cdp.reset();
 ```
 
-**Sau khi logout:**
-- `userId`, `profileId`, `userTraits`, `consents`, `scores`, `products`, `campaign` → xoá
-- `anonymousId`, `sessionId` → tạo mới
-- `deviceId` → giữ nguyên
+| | Hành động |
+|---|---|
+| `userId`, `profileId`, `userTraits` | Xoá |
+| `consents`, `scores`, `products`, `campaign` | Xoá |
+| `anonymous_id` | Tạo mới, lưu AsyncStorage |
+| `session_id` | Tạo mới, lưu AsyncStorage |
+| `device_id` | **Giữ nguyên** |
 
 ---
 
 ## Event Tracking
 
-### Track sự kiện
+### track — Custom event
 
 ```typescript
-cdp.track('button_click', {
-  button_name: 'apply_loan',
-  screen: 'HomeScreen',
-  loan_amount: 50_000_000,
-});
-
-cdp.track('form_submit', {
-  form_name: 'personal_info',
-  step: 2,
-  duration_seconds: 45,
-});
+cdp.track(eventName, properties?)
 ```
 
-> **Batching:** Events được gom theo `batchSize` hoặc `batchInterval`, sau đó gửi một lần qua `POST /v2/events/batch`. Nếu `batchSize = 1`, mỗi event được gửi ngay qua `POST /v2/events/track`.
+```typescript
+cdp.track('loan_viewed', {
+  loan_id: 'LOAN_001',
+  amount:  50_000_000,
+  term:    24,
+  type:    'consumer',
+});
 
-Mỗi event tự động bao gồm:
+cdp.track('button_click', { button: 'apply_now', screen: 'LoanDetailScreen' });
 
-| Trường | Nguồn |
-|---|---|
-| `event_id` | UUID mới mỗi event |
-| `session_id` | Session hiện tại |
-| `device_id` | Persistent per device |
-| `profile_id` | Từ CDP sau khi login |
-| `anonymous_id` | Persistent, rotate khi logout |
-| `platforms` | Từ `react-native-device-info` |
-| `context.locale` | Ngôn ngữ thiết bị |
-| `context.timezone` | Múi giờ thiết bị |
-| `context.app.version` | Phiên bản app |
-| `event_time` | ISO 8601 tại thời điểm gọi |
+cdp.track('form_submitted', { form: 'loan_application', success: true });
+```
 
 ---
 
-### Track màn hình (`screen`)
+### screen — Màn hình
+
+Track lượt xem màn hình. Gửi event `screen_view`.
 
 ```typescript
 cdp.screen('HomeScreen');
-
-cdp.screen('LoanDetailScreen', {
-  loan_id: 'LOAN_001',
-  loan_amount: 50_000_000,
-});
+cdp.screen('LoanDetailScreen', { loan_code: 'CONSUMER_24M' });
+cdp.screen('ProfileScreen',    { tab: 'personal_info' });
 ```
 
-Tương đương với:
+---
+
+### Tích hợp React Navigation
+
 ```typescript
-cdp.track('screen_view', { screen_name: 'HomeScreen', ...properties });
+// App.tsx
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+import { getCdp } from './lib/cdp';
+
+export default function App() {
+  const navRef = useNavigationContainerRef();
+
+  return (
+    <NavigationContainer
+      ref={navRef}
+      onReady={() => {
+        const name = navRef.getCurrentRoute()?.name;
+        if (name) getCdp().screen(name);
+      }}
+      onStateChange={() => {
+        const name = navRef.getCurrentRoute()?.name;
+        if (name) getCdp().screen(name);
+      }}
+    >
+      {/* Stack / Tab / Drawer navigators */}
+    </NavigationContainer>
+  );
+}
 ```
 
 ---
 
-### Flush thủ công
+### Batch Processing
+
+Events được gom vào **queue** rồi flush theo điều kiện:
+
+| Điều kiện | Mô tả |
+|---|---|
+| `batchSize` đạt ngưỡng | Mặc định 10 events |
+| `batchInterval` timeout | Mặc định 5 000 ms |
+| `flush()` gọi thủ công | Ngay lập tức |
+| App vào background | Gọi `flush()` trước `AppState` change |
+
+---
 
-Gửi toàn bộ events đang trong queue ngay lập tức. Hữu ích khi app sắp vào background hoặc trước khi đăng xuất.
+### flush — Gửi ngay
 
 ```typescript
 await cdp.flush();
 ```
 
----
+```typescript
+// Flush khi app vào background
+import { AppState } from 'react-native';
 
-## Lấy thông tin định danh
+AppState.addEventListener('change', async (state) => {
+  if (state === 'background') {
+    await cdp.flush();
+  }
+});
+```
 
-```typescript
-const ids = cdp.getUserIdentities();
-// {
-//   user_id: 'user_123',
-//   profile_id: 'cdp_abc123',
-//   anonymous_id: 'uuid-...',
-//   device_id: 'uuid-...',
-//   session_id: 'uuid-...',
-// }
+---
 
-cdp.getProfileId();   // profile_id từ CDP
-cdp.getDeviceId();    // persistent device identifier
-cdp.getSessionId();   // session hiện tại (mới mỗi lần mở app)
+### destroy — Dọn dẹp
 
-cdp.getUserAttribute('phone');    // lấy giá trị trait cụ thể
+```typescript
+await cdp.destroy();
 ```
 
+Flush queue còn lại và xoá timer. Không xoá user data.
+
 ---
 
 ## Bảo mật
 
-### HMAC Signature
+### HMAC-SHA256 Signature
+
+Mọi request đến CDP API đều được ký tự động.
 
-Mọi request tự động được ký. Header `X-Signatures` được tính theo công thức:
+**Headers:**
 
 ```
-X-Signatures = Base64(HMAC-SHA256(source + "|" + timestamp + "|" + payload))
+X-Api-Key:    <apiKey>
+X-Source:     <source>
+X-Timestamp:  <unix_timestamp_s>
+X-Signatures: <base64_signature>
+X-Trace-Id:   <uuid>
+Content-Type: application/json
+isTest:       false
 ```
 
-### Mã hoá PII (AES-256-CBC)
+**Công thức:**
 
-Khi `enableEncryption: true`, các trường nhạy cảm sau được mã hoá trước khi gửi:
+```
+signature = Base64( HMAC-SHA256(secretKey, message) )
+message   = source + "|" + timestamp + "|" + JSON(payload)
+```
+
+> **Lưu ý:** RN SDK dùng timestamp tính bằng **giây** (khác với Web SDK dùng milliseconds).
+
+---
+
+### AES-256-CBC Encryption
+
+Khi `enableEncryption: true`, các trường PII được mã hoá.
 
-`full_name`, `first_name`, `last_name`, `phone`, `email`, `idcard`, `old_idcard`, `gender`, `dob`, `address`, `religion`
+**Các trường PII bị mã hoá:**
+
+| Trường | Mô tả |
+|---|---|
+| `phone` | Số điện thoại |
+| `email` | Email |
+| `idcard` | CMND/CCCD mới |
+| `old_idcard` | CMND cũ |
+| `address` | Địa chỉ |
+| `religion` | Tôn giáo |
+| `full_name` | Họ tên đầy đủ |
+| `first_name` | Tên |
+| `last_name` | Họ |
+| `gender` | Giới tính |
+| `dob` | Ngày sinh |
+
+**Công thức:**
 
-Công thức mã hoá:
 ```
-traits = Base64(IV + AES_CBC_PKCS5(key, plaintext_traits_json))
-Key    = SHA256(secretKey + X-Timestamp)  →  32 bytes (AES-256)
-IV     = Random 16 bytes
+encrypted = Base64( IV[16 bytes] || AES_CBC_PKCS7( key, IV, plaintext ) )
+
+key       = SHA256( secretKey + timestamp )
+IV        = random 16 bytes (prepend vào ciphertext)
+plaintext = JSON.stringify({ chỉ các trường PII })
 ```
 
-Sử dụng thư viện `crypto-js` — pure JavaScript, không cần link native, hoạt động trên cả iOS và Android.
+> **Lưu ý:** Không bật trên dev/staging nếu server chưa cấu hình giải mã. Dùng `enableEncryption: false`.
 
 ---
 
-## Dependencies
+### Best Practices
 
-| Package | Lý do |
-|---|---|
-| `@react-native-async-storage/async-storage` | Lưu `device_id`, `anonymous_id`, `profile_id` |
-| `react-native-device-info` | Lấy `brand`, `model`, `os_version`, `app_version` |
-| `crypto-js` | HMAC-SHA256 signature + AES-256-CBC encryption (pure JS) |
+- Không log `secretKey` hay `apiKey` vào console production.
+- Bật `debug: false` trên production build.
+- Rotate key theo chính sách CDP team.
+- Dùng environment variables, không hardcode credentials.
+
+```typescript
+// ✅ Đúng — dùng env vars
+import Config from 'react-native-config';
+
+const cdp = await CdpRnSdk.create({
+  apiKey:    Config.CDP_API_KEY,
+  secretKey: Config.CDP_SECRET_KEY,
+  source:    'DOP',
+  serviceName: 'VC_APP',
+  debug:     __DEV__,
+});
+```
+
+```bash
+# .env
+CDP_API_KEY=YOUR_API_KEY
+CDP_SECRET_KEY=YOUR_SECRET_KEY
+CDP_BASE_URL=https://stg-ingestlog.vietcredit.com.vn
+
+# .env.production
+CDP_API_KEY=<production_key>
+CDP_SECRET_KEY=<production_secret>
+CDP_BASE_URL=https://ingestlog.vietcredit.com.vn
+```
 
 ---
 
-## API Reference
+## Tích hợp React Navigation đầy đủ
 
-### `CdpRnSdk.create(config)`
+Setup hoàn chỉnh với auto screen tracking và AppState flush:
 
-| Tham số | Kiểu | Bắt buộc | Mặc định |
-|---|---|---|---|
-| `apiKey` | `string` | ✓ | |
-| `secretKey` | `string` | ✓ | |
-| `source` | `string` | ✓ | |
-| `serviceName` | `string` | ✓ | |
-| `baseUrl` | `string` | | `https://stg-ingestlog.vietcredit.com.vn` |
-| `isTest` | `boolean` | | `false` |
-| `debug` | `boolean` | | `false` |
-| `batchSize` | `number` | | `10` |
-| `batchInterval` | `number` (ms) | | `5000` |
-| `enableEncryption` | `boolean` | | `true` |
-
-### Endpoint mapping
-
-| Method SDK | HTTP | Endpoint |
-|---|---|---|
-| `identifyUser()` / `identify()` | POST | `/v1/profiles/track` |
-| `updateProfile()` | POST | `/v1/profiles/update` |
-| `getProfile()` | GET | `/v1/profiles/get/{profile_id}` |
-| `track()` (batchSize=1) | POST | `/v2/events/track` |
-| `track()` / `flush()` (batch) | POST | `/v2/events/batch` |
-| Trait setters | POST | `/v1/profiles/track` (type: update) |
-| `destroy_session()` | POST | `/v1/profiles/track` (type: logout) |
+```typescript
+// src/lib/cdp.ts
+import { CdpRnSdk } from 'vc-cdp-rn-sdk';
+
+let _cdp: CdpRnSdk | null = null;
+
+export async function initCdp(): Promise<CdpRnSdk> {
+  _cdp = await CdpRnSdk.create({
+    apiKey:     process.env.CDP_API_KEY!,
+    secretKey:  process.env.CDP_SECRET_KEY!,
+    source:     'DOP',
+    serviceName: 'VC_APP',
+    baseUrl:    process.env.CDP_BASE_URL,
+    debug:      __DEV__,
+  });
+  return _cdp;
+}
+
+export function getCdp(): CdpRnSdk {
+  if (!_cdp) throw new Error('CDP SDK chưa được khởi tạo. Gọi initCdp() trước.');
+  return _cdp;
+}
+```
+
+```typescript
+// App.tsx
+import React, { useEffect, useRef } from 'react';
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+import { AppState, AppStateStatus } from 'react-native';
+import { initCdp, getCdp } from './lib/cdp';
+
+export default function App() {
+  const navRef   = useNavigationContainerRef();
+  const appState = useRef(AppState.currentState);
+
+  useEffect(() => {
+    initCdp();
+  }, []);
+
+  // Flush khi app vào background
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', async (next: AppStateStatus) => {
+      if (appState.current === 'active' && next.match(/inactive|background/)) {
+        await getCdp().flush();
+      }
+      appState.current = next;
+    });
+    return () => sub.remove();
+  }, []);
+
+  return (
+    <NavigationContainer
+      ref={navRef}
+      onReady={() => {
+        const name = navRef.getCurrentRoute()?.name;
+        if (name) getCdp().screen(name);
+      }}
+      onStateChange={() => {
+        const name = navRef.getCurrentRoute()?.name;
+        if (name) getCdp().screen(name);
+      }}
+    >
+      <RootNavigator />
+    </NavigationContainer>
+  );
+}
+```
+
+```typescript
+// Hook tiện lợi
+// hooks/useCdp.ts
+import { getCdp } from '../lib/cdp';
+import type { CdpRnSdk } from 'vc-cdp-rn-sdk';
+
+export function useCdp(): CdpRnSdk {
+  return getCdp();
+}
+```
+
+```typescript
+// Identify sau đăng nhập
+async function handleLogin(phone: string, password: string) {
+  const user = await authApi.login(phone, password);
+  await getCdp().identifyUser(user.id, {
+    phone:     user.phone,
+    email:     user.email,
+    full_name: user.name,
+  });
+  navigation.navigate('Home');
+}
+
+// Đăng xuất
+async function handleLogout() {
+  await authApi.logout();
+  await getCdp().destroy_session();
+  navigation.reset({ index: 0, routes: [{ name: 'Login' }] });
+}
+```
 
 ---
 
-## Tài liệu chi tiết
+## API Reference
 
-| File | Nội dung |
-|---|---|
-| [docs/getting-started.md](docs/getting-started.md) | Hướng dẫn bắt đầu từ đầu |
-| [docs/profile.md](docs/profile.md) | Profile, traits, consents, scores, products |
-| [docs/events.md](docs/events.md) | Event tracking, batching, screen view |
-| [docs/security.md](docs/security.md) | HMAC signature, AES encryption |
-| [docs/api-reference.md](docs/api-reference.md) | Toàn bộ API với type signatures |
-| [docs/integration-react-navigation.md](docs/integration-react-navigation.md) | React Navigation integration |
+### Factory
+
+```typescript
+static async create(config: CdpRnConfig): Promise<CdpRnSdk>
+```
+
+### CdpRnConfig
+
+```typescript
+interface CdpRnConfig {
+  apiKey:             string;    // bắt buộc
+  secretKey:          string;    // bắt buộc
+  source:             string;    // bắt buộc — kênh tích hợp
+  serviceName:        string;    // bắt buộc — VC_APP | DOP | LOS | LMS
+  baseUrl?:           string;    // mặc định staging
+  isTest?:            boolean;   // mặc định false
+  debug?:             boolean;   // mặc định false
+  batchSize?:         number;    // mặc định 10
+  batchInterval?:     number;    // mặc định 5000 ms
+  enableEncryption?:  boolean;   // mặc định true
+}
+```
+
+### Profile Methods
+
+```typescript
+async identifyUser(userId: string, traits?: UserTraits, partyType?: 'PERSON' | 'ORG'): Promise<this>
+async identify(userId: string, traits?: UserTraits): Promise<this>   // alias
+
+async updateProfile(payload: {
+  profile_id?: string;
+  traits?:     UserTraits;
+  consents?:   ConsentInfo[];
+  scores?:     ScoreInfo[];
+  products?:   ProductInfo[];
+  metadata?:   Record<string, unknown>;
+}): Promise<ProfileResponse | undefined>
+
+async getProfile(profileId?: string): Promise<ProfileData | undefined>
+```
+
+### Trait Setter Methods (chainable → `this`)
+
+```typescript
+add_first_name(v: string): this
+add_last_name(v: string): this
+add_user_name(v: string): this
+add_email(v: string): this
+add_mobile(v: string): this
+add_gender(v: 'M' | 'F' | 'O'): this
+add_birthday(v: string | Date): this
+add_idcard(v: string): this
+add_old_idcard(v: string): this
+add_address(v: string): this
+add_occupation(v: string): this
+add_nationality(v: string): this
+add_marital_status(v: string): this
+add_religion(v: string): this
+add_zalo_id(v: string): this
+add_tiktok_id(v: string): this
+add_user_attribute(name: string, value: unknown): this
+add_user_attributes(attrs: UserTraits): this
+setUserAttributes(attrs: UserTraits): this
+```
+
+### Consent / Score / Product / Campaign Methods
+
+```typescript
+setConsents(consents: ConsentInfo[]): this
+setScores(scores: ScoreInfo[]): this
+setProducts(products: ProductInfo[]): this
+setMetadata(meta: Record<string, unknown>): this
+setCampaign(info: CampaignInfo): this
+setPlatform(info: PlatformInfo): this
+setPushToken(token: string): this
+```
+
+### Event Methods
+
+```typescript
+track(eventName: string, properties?: Record<string, unknown>): void
+screen(screenName: string, properties?: Record<string, unknown>): void
+async flush(): Promise<void>
+```
+
+### Session & Identity Methods
+
+```typescript
+getUserIdentities(): UserIdentities
+getProfileId(): string | null
+getDeviceId(): string
+getSessionId(): string
+getUserAttribute(name: keyof UserTraits): unknown
+
+async destroy_session(): Promise<this>
+async reset(): Promise<this>    // alias
+async destroy(): Promise<void>  // cleanup timers + flush
+```
+
+### Types
+
+```typescript
+interface UserTraits {
+  full_name?:      string;
+  first_name?:     string;
+  last_name?:      string;
+  phone?:          string;          // 🔒 PII
+  email?:          string;          // 🔒 PII
+  gender?:         'M' | 'F' | 'O';
+  dob?:            string;          // 'yyyy-MM-dd'
+  idcard?:         string;          // 🔒 PII
+  old_idcard?:     string;          // 🔒 PII
+  address?:        string;          // 🔒 PII
+  occupation?:     string;
+  nationality?:    string;
+  marital_status?: string;
+  religion?:       string;          // 🔒 PII
+  zalo_id?:        string;
+  tiktok_id?:      string;
+  mps_verified?:   boolean;
+  kyc_status?:     string;
+  [key: string]:   unknown;
+}
+
+interface ConsentInfo {
+  consent_type:  string;
+  status:        boolean;
+  consent_date?: string;   // 'yyyy-MM-dd'
+}
+
+interface ScoreInfo {
+  score_type:   string;
+  score_value:  number;
+  score_date?:  string;
+}
+
+interface ProductInfo {
+  product_code:  string;
+  product_name?: string;
+  status?:       string;
+}
+
+interface UserIdentities {
+  user_id:      string | null;
+  profile_id:   string | null;
+  anonymous_id: string;
+  device_id:    string;
+  session_id:   string;
+}
+
+interface ProfileResponse {
+  code:           number;
+  message:        string;
+  transaction_id: string;
+  profile_id:     string;
+}
+```

package/docs/getting-started.md

@@ -149,8 +149,8 @@ await cdp.destroy_session();
 
 ## Bước tiếp theo
 
-- [Profile & Traits →](profile.md)
-- [Event Tracking →](events.md)
-- [Tích hợp React Navigation →](integration-react-navigation.md)
-- [Bảo mật →](security.md)
-- [API Reference →](api-reference.md)
+- [Profile & Traits →](https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/blob/master/vc-cdp-rn-sdk/docs/profile.md)
+- [Event Tracking →](https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/blob/master/vc-cdp-rn-sdk/docs/events.md)
+- [Tích hợp React Navigation →](https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/blob/master/vc-cdp-rn-sdk/docs/integration-react-navigation.md)
+- [Bảo mật →](https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/blob/master/vc-cdp-rn-sdk/docs/security.md)
+- [API Reference →](https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/blob/master/vc-cdp-rn-sdk/docs/api-reference.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vc-cdp-rn-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CDP SDK for React Native - Customer Data Platform tracking for iOS and Android",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,12 @@
   ],
   "author": "VietCredit",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.ovp.vn/dlc/vc-cdk-sdk.git",
+    "directory": "vc-cdp-rn-sdk"
+  },
+  "homepage": "https://gitlab.ovp.vn/dlc/vc-cdk-sdk/-/tree/master/vc-cdp-rn-sdk#readme",
   "peerDependencies": {
     "@react-native-async-storage/async-storage": ">=1.17.0",
     "react": ">=17.0.0",