vc-cdp-rn-sdk 0.1.0 → 0.1.2

package/docs/getting-started.md

@@ -0,0 +1,156 @@
+# Getting Started
+
+Hướng dẫn tích hợp `vc-cdp-rn-sdk` vào React Native từ đầu.
+
+---
+
+## 1. Cài đặt
+
+```bash
+npm install vc-cdp-rn-sdk
+```
+
+### Peer Dependencies
+
+SDK yêu cầu các package sau phải được cài riêng trong project:
+
+```bash
+npm install @react-native-async-storage/async-storage
+npm install react-native-device-info
+```
+
+#### iOS — link native modules
+
+```bash
+cd ios && pod install
+```
+
+#### Android
+
+Không cần thêm cấu hình nếu dùng React Native >= 0.68 (auto-linking).
+
+---
+
+## 2. Khởi tạo
+
+Khởi tạo SDK **một lần duy nhất** tại entry point của app (thường là `App.tsx`). SDK dùng `AsyncStorage` nên init là **async**.
+
+```typescript
+// App.tsx
+import { CdpRnSdk } from 'vc-cdp-rn-sdk';
+
+let cdp: CdpRnSdk;
+
+export async function initCdp() {
+  cdp = await CdpRnSdk.create({
+    apiKey:     'YOUR_API_KEY',
+    secretKey:  'YOUR_SECRET_KEY',
+    source:     'DOP',
+    serviceName: 'VC_APP',
+    baseUrl:    'https://ingestlog.vietcredit.com.vn',
+  });
+}
+
+export { cdp };
+```
+
+```typescript
+// App.tsx — gọi trong useEffect
+import { useEffect } from 'react';
+import { initCdp } from './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.
+
+---
+
+## 3. Track event đầu tiên
+
+```typescript
+import { cdp } from './cdp';
+
+// Track màn hình đầu tiên
+cdp.screen('SplashScreen');
+
+// Custom event
+cdp.track('app_open', { platform: 'android', version: '2.1.0' });
+```
+
+---
+
+## 4. Identify user sau đăng nhập
+
+```typescript
+await cdp.identifyUser('user_001', {
+  phone:     '0901234567',
+  email:     'user@example.com',
+  full_name: 'Nguyễn Văn A',
+});
+
+console.log(cdp.getProfileId()); // → "177671850461184000"
+```
+
+---
+
+## 5. Track events sau login
+
+```typescript
+cdp.track('loan_viewed', {
+  loan_id: 'LOAN_001',
+  amount:  50_000_000,
+  term:    24,
+});
+
+cdp.screen('LoanDetailScreen', { loan_code: 'CONSUMER_24M' });
+```
+
+---
+
+## 6. Đăng xuất
+
+```typescript
+await cdp.destroy_session();
+```
+
+---
+
+## 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 phát triển (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` |
+
+---
+
+## Bước tiếp theo
+
+- [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/docs/integration-react-navigation.md

@@ -0,0 +1,202 @@
+# Tích hợp React Navigation
+
+Hướng dẫn auto-track màn hình khi navigate trong React Navigation.
+
+---
+
+## Setup cơ bản
+
+```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;
+}
+```
+
+---
+
+## Auto-track Screen (React Navigation 6+)
+
+```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>
+  );
+}
+```
+
+---
+
+## Track trong Screen Component
+
+```typescript
+// screens/LoanDetailScreen.tsx
+import React, { useEffect } from 'react';
+import { View, Button } from 'react-native';
+import { getCdp } from '../lib/cdp';
+
+export function LoanDetailScreen({ route }: any) {
+  const { loanId, amount } = route.params;
+  const cdp = getCdp();
+
+  useEffect(() => {
+    cdp.track('loan_detail_viewed', { loan_id: loanId, amount });
+  }, [loanId]);
+
+  const handleApply = () => {
+    cdp.track('loan_apply_clicked', { loan_id: loanId, amount });
+    // navigate to form
+  };
+
+  return (
+    <View>
+      <Button title="Đăng ký ngay" onPress={handleApply} />
+    </View>
+  );
+}
+```
+
+---
+
+## Identify sau đăng nhập
+
+```typescript
+// screens/LoginScreen.tsx
+import { getCdp } from '../lib/cdp';
+
+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
+
+```typescript
+// screens/ProfileScreen.tsx
+import { getCdp } from '../lib/cdp';
+
+async function handleLogout() {
+  await authApi.logout();
+  await getCdp().destroy_session();
+  navigation.reset({ index: 0, routes: [{ name: 'Login' }] });
+}
+```
+
+---
+
+## Hook tiện lợi
+
+```typescript
+// hooks/useCdp.ts
+import { getCdp } from '../lib/cdp';
+import type { CdpRnSdk } from 'vc-cdp-rn-sdk';
+
+export function useCdp(): CdpRnSdk {
+  return getCdp();
+}
+```
+
+```typescript
+// Dùng trong component
+function ProductCard({ product }: { product: Product }) {
+  const cdp = useCdp();
+
+  return (
+    <Pressable onPress={() => cdp.track('product_tapped', { code: product.code })}>
+      <Text>{product.name}</Text>
+    </Pressable>
+  );
+}
+```
+
+---
+
+## Environment Variables (react-native-config)
+
+```bash
+# .env
+CDP_API_KEY=eff9ba9a-5b10-4fc0-af23-e2641b46d307
+CDP_SECRET_KEY=91ed726c-60e8-4ef7-ab2d-112b5324f9a1
+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
+```
+
+```typescript
+import Config from 'react-native-config';
+
+const cdp = await CdpRnSdk.create({
+  apiKey:    Config.CDP_API_KEY,
+  secretKey: Config.CDP_SECRET_KEY,
+  baseUrl:   Config.CDP_BASE_URL,
+  source:    'DOP',
+  serviceName: 'VC_APP',
+  debug:     __DEV__,
+});
+```

package/docs/profile.md

@@ -0,0 +1,196 @@
+# Profile & Traits
+
+Hướng dẫn quản lý thông tin người dùng trên CDP cho React Native.
+
+---
+
+## identifyUser() — Đăng nhập
+
+```typescript
+await cdp.identifyUser(userId, traits?, partyType?)
+```
+
+| Tham số | Kiểu | Bắt buộc | Mô tả |
+|---|---|---|---|
+| `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'` |
+
+```typescript
+// 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',
+});
+
+// Tổ chức
+await cdp.identifyUser('org_001', {
+  full_name: 'Công ty TNHH ABC',
+  phone:     '0281234567',
+  email:     'contact@abc.vn',
+}, 'ORG');
+```
+
+---
+
+## Trait Setters — Cập nhật từng thuộc tính
+
+Chainable. Mỗi setter gọi ngay `POST /v1/profiles/track` (type: update).
+
+```typescript
+cdp
+  .add_first_name('Văn A')
+  .add_last_name('Nguyễn')
+  .add_user_name('Nguyễn Văn A')
+  .add_email('user@example.com')
+  .add_mobile('0901234567')
+  .add_gender('M')
+  .add_birthday('1990-01-15')       // hoặc new Date('1990-01-15')
+  .add_idcard('012345678901')
+  .add_old_idcard('123456789')
+  .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_user_001')
+  .add_tiktok_id('tiktok_user_001');
+```
+
+| 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 |
+| `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 |
+| `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 |
+| `add_zalo_id(v)` | `zalo_id` | |
+| `add_tiktok_id(v)` | `tiktok_id` | |
+| `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 |
+
+---
+
+## updateProfile() — Force-update
+
+```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: 'data_sharing',    status: true },
+]);
+```
+
+---
+
+## Scores
+
+```typescript
+cdp.setScores([
+  { score_type: 'credit_score', score_value: 720, score_date: '2025-06-01' },
+]);
+```
+
+---
+
+## Products
+
+```typescript
+cdp.setProducts([
+  { product_code: 'LOAN_CONSUMER', product_name: 'Vay tiêu dùng', status: 'active' },
+]);
+```
+
+---
+
+## Metadata, Campaign, Push Token
+
+```typescript
+cdp.setMetadata({ schema_version: '2.0', referral_code: 'REF123' });
+
+cdp.setCampaign({
+  utm_source:   'facebook',
+  utm_medium:   'cpc',
+  utm_campaign: 'summer_loan_2025',
+});
+
+cdp.setPushToken('ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]');
+// hoặc FCM token trên Android
+cdp.setPushToken('fcm_token_abc123...');
+```
+
+---
+
+## getUserIdentities()
+
+```typescript
+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');
+```
+
+---
+
+## destroy_session() — Đăng xuất
+
+```typescript
+await cdp.destroy_session();
+// hoặc alias:
+await cdp.reset();
+```
+
+| | 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** |

package/docs/security.md

@@ -0,0 +1,111 @@
+# Bảo mật
+
+---
+
+## HMAC-SHA256 Signature
+
+Mọi request đến CDP API đều được ký tự động.
+
+### Headers
+
+```
+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
+```
+
+### Công thức
+
+```
+signature = Base64( HMAC-SHA256(secretKey, message) )
+message   = source + "|" + timestamp + "|" + JSON(payload)
+```
+
+| Thành phần | Mô tả |
+|---|---|
+| `secretKey` | Secret Key CDP cấp |
+| `source` | Kênh tích hợp (`DOP`, ...) |
+| `timestamp` | Unix timestamp tính bằng **giây** (RN SDK) hoặc **ms** (Web SDK) |
+| `payload` | Body JSON string (GET request: chuỗi rỗng `""`) |
+
+---
+
+## AES-256-CBC Encryption
+
+Khi `enableEncryption: true`, các trường PII được mã hoá.
+
+### 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
+
+```
+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 })
+```
+
+### 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`.
+- Production: `enableEncryption: true` (mặc định).
+
+```typescript
+// Development
+const cdp = await CdpRnSdk.create({
+  enableEncryption: false,
+  isTest: true,
+});
+
+// Production
+const cdp = await CdpRnSdk.create({
+  enableEncryption: true,
+});
+```
+
+---
+
+## Lưu trữ
+
+| Dữ liệu | Nơi lưu | Vòng đời |
+|---|---|---|
+| `device_id` | AsyncStorage | Vĩnh viễn (đến khi xoá app) |
+| `anonymous_id` | AsyncStorage | Vĩnh viễn (rotate khi logout) |
+| `session_id` | AsyncStorage | Tạo mới mỗi lần `create()` |
+| `profile_id` | AsyncStorage | Xoá khi `destroy_session()` |
+
+---
+
+## Best Practices
+
+- 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
+const cdp = await CdpRnSdk.create({
+  apiKey:    Config.CDP_API_KEY,    // react-native-config
+  secretKey: Config.CDP_SECRET_KEY,
+});
+```

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "vc-cdp-rn-sdk",
-  "version": "0.1.0",
+  "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",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "scripts": {
     "build": "tsc",
@@ -25,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",