SkyFi React Native SDK

🇻🇳 Tiếng Việt | 🇬🇧 English

Thư viện SDK toàn diện để tích hợp các dịch vụ SkyFi vào ứng dụng React Native. SDK này cung cấp bộ components UI hoàn chỉnh, điều hướng và các services để xây dựng tính năng quản lý eSIM, gói du lịch và các tính năng viễn thông.

Tính năng

• 📱 Quản lý và kích hoạt eSIM hoàn chỉnh
• 🌍 Duyệt và mua các gói eSIM du lịch
• 🛒 Hệ thống giỏ hàng và thanh toán
• 💳 Tích hợp nhiều phương thức thanh toán
• 📊 Theo dõi dung lượng dữ liệu và nạp tiền
• 🔐 Quản lý xác thực và hồ sơ người dùng
• 🎨 Components UI có thể tùy chỉnh với hỗ trợ theme
• 🌐 Hỗ trợ đa ngôn ngữ (i18n) - Tiếng Việt & Tiếng Anh
• 📄 Xem PDF, chữ ký điện tử và quản lý tài liệu
• 📹 Tích hợp video và camera
• 🔔 Thông báo đẩy và cập nhật thời gian thực

Cài đặt

1. Cài đặt SDK

Cài đặt package từ npm:

npm install skyfi-rnsdk

Hoặc với yarn:

yarn add skyfi-rnsdk

Sau khi cài đặt, SDK sẽ tự động chạy script kiểm tra các dependencies còn thiếu. Nếu có dependencies nào thiếu, bạn sẽ thấy hướng dẫn cài đặt trong terminal.

2. Cài đặt các Dependencies

SDK yêu cầu các dependencies sau để hoạt động đầy đủ. Dưới đây là danh sách đầy đủ các dependencies được sử dụng trong ứng dụng example:

Dependencies Cốt lõi (Bắt buộc)

Các dependencies này là bắt buộc để SDK hoạt động:

npm install \
  @react-native-async-storage/async-storage@^2.2.0 \
  @react-navigation/elements@^2.2.6 \
  @react-navigation/native@^7.1.20 \
  @react-navigation/stack@^7.6.4 \
  @rneui/base@^4.0.0-rc.8 \
  @rneui/themed@^4.0.0-rc.8 \
  axios@^1.13.2 \
  crypto-js@^4.2.0 \
  i18next@^25.6.2 \
  react-hook-form@^7.66.0 \
  react-i18next@^16.3.3 \
  react-native-gesture-handler@^2.29.1 \
  react-native-linear-gradient@^2.8.3 \
  react-native-safe-area-context@^5.6.2 \
  react-native-screens@^4.18.0 \
  react-native-svg@^15.15.0 \
  react-native-webview@^13.16.0 \
  zustand@^5.0.8

Hoặc với yarn:

yarn add \
  @react-native-async-storage/async-storage@^2.2.0 \
  @react-navigation/elements@^2.2.6 \
  @react-navigation/native@^7.1.20 \
  @react-navigation/stack@^7.6.4 \
  @rneui/base@^4.0.0-rc.8 \
  @rneui/themed@^4.0.0-rc.8 \
  axios@^1.13.2 \
  crypto-js@^4.2.0 \
  i18next@^25.6.2 \
  react-hook-form@^7.66.0 \
  react-i18next@^16.3.3 \
  react-native-gesture-handler@^2.29.1 \
  react-native-linear-gradient@^2.8.3 \
  react-native-safe-area-context@^5.6.2 \
  react-native-screens@^4.18.0 \
  react-native-svg@^15.15.0 \
  react-native-webview@^13.16.0 \
  zustand@^5.0.8

Dependencies Tùy chọn (Cho Tính năng Nâng cao)

Chỉ cài đặt những dependencies này nếu bạn cần các tính năng tương ứng:

npm install \
  @types/react-native-vector-icons@^6.4.18 \
  react-native-blob-util@^0.23.2 \
  react-native-fs@^2.20.0 \
  react-native-htmlview@^0.17.0 \
  react-native-pdf@^7.0.3 \
  react-native-permissions@^5.4.4 \
  react-native-signature-canvas@^5.0.1 \
  react-native-vector-icons@^10.3.0 \
  react-native-video@^6.17.0 \
  react-native-vision-camera@^4.7.3 \
  socket.io-client@^4.8.1

# Cài đặt react-native-in-browser từ GitHub (Bắt buộc nếu dùng tính năng browser)
npm install https://github.com/Leung190299/react-native-in-browser.git#main

Hoặc với yarn:

yarn add \
  @types/react-native-vector-icons@^6.4.18 \
  react-native-blob-util@^0.23.2 \
  react-native-fs@^2.20.0 \
  react-native-htmlview@^0.17.0 \
  react-native-pdf@^7.0.3 \
  react-native-permissions@^5.4.4 \
  react-native-signature-canvas@^5.0.1 \
  react-native-vector-icons@^10.3.0 \
  react-native-video@^6.17.0 \
  react-native-vision-camera@^4.7.3 \
  socket.io-client@^4.8.1

# Cài đặt react-native-in-browser từ GitHub
yarn add https://github.com/Leung190299/react-native-in-browser.git#main

⚠️ Lưu ý quan trọng:

• react-native-in-browser phải được cài đặt từ GitHub repository vì đây là phiên bản custom được tối ưu hóa cho SDK này. Không sử dụng package từ npm.
• Các version được chỉ định ở trên đã được kiểm thử và hoạt động ổn định với SDK
• Bạn có thể bỏ qua việc chỉ định version (ví dụ: @^2.2.0) để cài đặt version mới nhất, nhưng điều này có thể gây ra vấn đề tương thích

Cách cài đặt:

# Đúng ✅ - Cài đặt từ GitHub
npm install https://github.com/Leung190299/react-native-in-browser.git#main
# hoặc
yarn add https://github.com/Leung190299/react-native-in-browser.git#main

# Sai ❌ - Cài đặt từ npm
npm install react-native-in-browser

Hoặc thêm vào package.json:

{
  "dependencies": {
    "react-native-in-browser": "https://github.com/Leung190299/react-native-in-browser.git#main"
  }
}

Sau đó chạy:

npm install
# hoặc
yarn install

Lưu ý: Nếu bạn chỉ cần các tính năng cơ bản, bạn có thể bỏ qua một số dependencies nâng cao. Xem phần Bảng Ánh xạ Tính năng - Dependencies bên dưới để hiểu dependencies nào cần thiết cho từng tính năng cụ thể.

3. Cấu hình iOS

Đối với iOS, cài đặt các dependencies CocoaPods:

cd ios && pod install && cd ..

4. Cài đặt Vector Icons

Thêm các font icon vào dự án của bạn. Chỉnh sửa file ios/YourProjectName/Info.plist và thêm:

<key>UIAppFonts</key>
<array>
  <string>AntDesign.ttf</string>
  <string>Entypo.ttf</string>
  <string>EvilIcons.ttf</string>
  <string>Feather.ttf</string>
  <string>FontAwesome.ttf</string>
  <string>FontAwesome5_Brands.ttf</string>
  <string>FontAwesome5_Regular.ttf</string>
  <string>FontAwesome5_Solid.ttf</string>
  <string>Foundation.ttf</string>
  <string>Ionicons.ttf</string>
  <string>MaterialIcons.ttf</string>
  <string>MaterialCommunityIcons.ttf</string>
  <string>SimpleLineIcons.ttf</string>
  <string>Octicons.ttf</string>
  <string>Zocial.ttf</string>
  <string>Fontisto.ttf</string>
</array>

Đối với Android, các font sẽ tự động được liên kết.

Hoặc sử dụng react-native-asset để tự động liên kết fonts:

# Cài đặt react-native-asset
npm install -g react-native-asset

# Tạo file react-native.config.js trong thư mục gốc nếu chưa có
cat > react-native.config.js << 'EOF'
module.exports = {
  assets: ['./node_modules/react-native-vector-icons/Fonts'],
};
EOF

# Liên kết fonts
npx react-native-asset

5. Cấu hình Native Modules

iOS

Thêm các permissions vào file Info.plist nếu sử dụng tính năng camera, ảnh hoặc vị trí:

<key>NSCameraUsageDescription</key>
<string>Chúng tôi cần quyền truy cập camera để quét mã QR và chụp ảnh</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Chúng tôi cần quyền truy cập thư viện ảnh để lưu hình ảnh</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Chúng tôi cần quyền truy cập vị trí để cung cấp dịch vụ tốt hơn</string>

Android

Cập nhật file android/app/build.gradle:

android {
    ...
    minSdkVersion 24  // Đảm bảo minSdk ít nhất là 24
}

Thêm permissions vào AndroidManifest.xml nếu cần:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Hướng dẫn Sử dụng Nhanh

1. Cấu hình Provider

Bọc ứng dụng của bạn với SkyFiProvider:

import React from 'react';
import { SkyFiProvider } from 'skyfi-rnsdk';

export default function App() {
  return (
    <SkyFiProvider
      config={{
        environment: 'development', // hoặc 'production'
        debug: true,
        defaultLanguage: 'vi', // hoặc 'en'
      }}
    >
      {/* Nội dung ứng dụng của bạn */}
    </SkyFiProvider>
  );
}

2. Sử dụng Navigator Hoàn chỉnh

SDK cung cấp bộ navigation stack đầy đủ với tất cả các màn hình:

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { SkyFiProvider, SkyFiNavigator } from 'skyfi-rnsdk';

export default function App() {
  return (
    <SkyFiProvider
      config={{
        environment: 'development',
        defaultLanguage: 'vi',
      }}
    >
      <NavigationContainer>
        <SkyFiNavigator />
      </NavigationContainer>
    </SkyFiProvider>
  );
}

3. Tích hợp Từng Màn hình Riêng lẻ

Bạn cũng có thể sử dụng từng màn hình và components riêng biệt:

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import {
  SkyFiProvider,
  PackagesScreen,
  CartScreen,
  useAuth,
  usePackage,
} from 'skyfi-rnsdk';

const Stack = createStackNavigator();

function MyCustomScreen() {
  const { user, login, logout } = useAuth();
  const { packages, loading } = usePackage();

  return (
    <View>
      {/* UI tùy chỉnh sử dụng hooks và dữ liệu từ SDK */}
    </View>
  );
}

export default function App() {
  return (
    <SkyFiProvider config={{ defaultLanguage: 'vi' }}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Packages" component={PackagesScreen} />
          <Stack.Screen name="Cart" component={CartScreen} />
          <Stack.Screen name="Custom" component={MyCustomScreen} />
        </Stack.Navigator>
      </NavigationContainer>
    </SkyFiProvider>
  );
}

4. Ví dụ Tích hợp Đầy đủ

Dựa trên ứng dụng example trong SDK:

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import {
  SkyFiProvider,
  SkyFiNavigator,
  PackagesScreen,
  CartScreen,
  ModalProvider,
} from 'skyfi-rnsdk';

const Stack = createStackNavigator();

// Màn hình trang chủ tùy chỉnh
const HomeScreen = ({ navigation }) => {
  return (
    <View style={{ flex: 1, padding: 20 }}>
      <Text style={{ fontSize: 24, marginBottom: 20 }}>
        Chào mừng đến SkyFi
      </Text>

      {/* Mở toàn bộ ứng dụng SkyFi */}
      <TouchableOpacity
        onPress={() => navigation.navigate('SkyFiApp')}
        style={{ backgroundColor: '#007AFF', padding: 15, borderRadius: 10 }}
      >
        <Text style={{ color: 'white', textAlign: 'center' }}>
          🌐 Mở Ứng dụng SkyFi Đầy đủ
        </Text>
      </TouchableOpacity>

      {/* Hoặc điều hướng đến từng màn hình riêng */}
      <TouchableOpacity
        onPress={() => navigation.navigate('Packages')}
        style={{ backgroundColor: '#5856D6', padding: 15, borderRadius: 10, marginTop: 10 }}
      >
        <Text style={{ color: 'white', textAlign: 'center' }}>
          📦 Xem Gói Dịch vụ
        </Text>
      </TouchableOpacity>

      <TouchableOpacity
        onPress={() => navigation.navigate('Cart')}
        style={{ backgroundColor: '#5856D6', padding: 15, borderRadius: 10, marginTop: 10 }}
      >
        <Text style={{ color: 'white', textAlign: 'center' }}>
          🛒 Xem Giỏ hàng
        </Text>
      </TouchableOpacity>
    </View>
  );
};

export default function App() {
  return (
    <SkyFiProvider
      config={{
        environment: 'development',
        debug: true,
        defaultLanguage: 'vi',
      }}
    >
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen
            name="Home"
            component={HomeScreen}
            options={{ title: 'Trang chủ' }}
          />

          {/* Navigator đầy đủ của SkyFi SDK */}
          <Stack.Screen
            name="SkyFiApp"
            component={SkyFiNavigator}
            options={{ headerShown: false }}
          />

          {/* Các màn hình riêng lẻ */}
          <Stack.Screen
            name="Packages"
            component={PackagesScreen}
            options={{ title: 'Gói Dịch vụ' }}
          />

          <Stack.Screen
            name="Cart"
            component={CartScreen}
            options={{ title: 'Giỏ hàng' }}
          />
        </Stack.Navigator>

        {/* Bắt buộc phải có ModalProvider */}
        <ModalProvider />
      </NavigationContainer>
    </SkyFiProvider>
  );
}

Components Có sẵn

Màn hình (Screens)

| Màn hình | Mô tả | |----------|-------| | HomeScreen | Trang chủ và dashboard | | PackagesScreen | Duyệt các gói dịch vụ có sẵn | | CartScreen | Giỏ hàng mua sắm | | CheckoutScreen | Quy trình thanh toán | | ProfileScreen | Quản lý hồ sơ người dùng | | LoginScreen | Đăng nhập và xác thực | | NotificationScreen | Thông báo | | SupportScreen | Hỗ trợ khách hàng |

Components UI

| Component | Mô tả | |-----------|-------| | BaseModal, BottomSheet, Sheet | Các modal và sheet tùy chỉnh | | CustomCheckbox | Checkbox tùy chỉnh | | LanguageSwitcher | Chuyển đổi ngôn ngữ | | LoadingProvider | Quản lý trạng thái loading | | ModalProvider | Provider cho modal system | | Cart Components | Các component liên quan đến giỏ hàng | | Form Components | Các component form (input, select, v.v.) | | SVG Icons | Bộ icon SVG tùy chỉnh |

Hooks

| Hook | Mô tả | |------|-------| | useAuth() | Quản lý xác thực và trạng thái người dùng | | usePackage() | Quản lý gói dịch vụ | | useI18n() | Đa ngôn ngữ và dịch thuật | | useAppSettings() | Cấu hình ứng dụng | | useAddress() | Quản lý địa chỉ | | useDebounce() | Debounce cho input | | useLoading() | Quản lý trạng thái loading | | useModal() | Quản lý modal |

Ví dụ Sử dụng Hooks

import { useAuth, usePackage, useI18n } from 'skyfi-rnsdk';

function MyComponent() {
  // Hook xác thực
  const { user, login, logout, isAuthenticated } = useAuth();

  // Hook quản lý gói
  const { packages, loading, error, fetchPackages } = usePackage();

  // Hook đa ngôn ngữ
  const { t, changeLanguage, currentLanguage } = useI18n();

  return (
    <View>
      <Text>{t('welcome')}</Text>

      {isAuthenticated ? (
        <Text>Xin chào, {user?.name}</Text>
      ) : (
        <Button onPress={login}>Đăng nhập</Button>
      )}

      {loading ? (
        <Text>Đang tải...</Text>
      ) : (
        packages.map((pkg) => (
          <Text key={pkg.id}>{pkg.name}</Text>
        ))
      )}

      <Button onPress={() => changeLanguage('en')}>
        Switch to English
      </Button>
    </View>
  );
}

Cấu hình

Cấu hình SDK

<SkyFiProvider
  config={{
    // Môi trường: 'development' | 'production'
    environment: 'development',
    // Ngôn ngữ mặc định: 'vi' | 'en'
    defaultLanguage: 'vi',
    // Cấu hình theme (tùy chọn)
    theme: {
      primaryColor: '#007AFF',
      secondaryColor: '#5856D6',
    },
  }}
>
  {/* App của bạn */}
</SkyFiProvider>

Tùy chỉnh Theme

import { ThemeProvider } from '@rneui/themed';
import { theme as skyfiTheme } from 'skyfi-rnsdk';

const customTheme = {
  ...skyfiTheme,
  colors: {
    ...skyfiTheme.colors,
    primary: '#FF6B6B',
    secondary: '#4ECDC4',
  },
};

<ThemeProvider theme={customTheme}>
  <SkyFiProvider>
    {/* App của bạn */}
  </SkyFiProvider>
</ThemeProvider>

Hỗ trợ Đa ngôn ngữ

SDK hỗ trợ sẵn Tiếng Việt và Tiếng Anh:

import { useI18n } from 'skyfi-rnsdk';

function LanguageSelector() {
  const { t, changeLanguage, currentLanguage } = useI18n();

  return (
    <View>
      <Text>{t('selectLanguage')}</Text>

      <TouchableOpacity onPress={() => changeLanguage('vi')}>
        <Text>🇻🇳 Tiếng Việt</Text>
      </TouchableOpacity>

      <TouchableOpacity onPress={() => changeLanguage('en')}>
        <Text>🇬🇧 English</Text>
      </TouchableOpacity>

      <Text>Ngôn ngữ hiện tại: {currentLanguage}</Text>
    </View>
  );
}

Bảng Ánh xạ Tính năng - Dependencies

| Tính năng | Dependencies Bắt buộc | |-----------|----------------------| | SDK Cơ bản | react-native-svg, react-native-linear-gradient, react-native-webview, axios, zustand, i18next, react-i18next | | Điều hướng | @react-navigation/native, @react-navigation/stack, @react-navigation/elements, react-native-gesture-handler, react-native-screens, react-native-safe-area-context | | Components UI | @rneui/base, @rneui/themed, react-native-vector-icons, @types/react-native-vector-icons | | Forms & Validation | react-hook-form, crypto-js | | Trình duyệt trong ứng dụng | react-native-in-browser | | Xem tài liệu | react-native-pdf, react-native-htmlview | | Thao tác file | react-native-fs, react-native-blob-util | | Chữ ký điện tử | react-native-signature-canvas | | Tính năng Video | react-native-video | | Tính năng Camera | react-native-vision-camera, react-native-permissions | | Cập nhật thời gian thực | socket.io-client | | Lưu trữ dữ liệu | @react-native-async-storage/async-storage |

Xử lý Sự cố

Lỗi NativeEventEmitter

Nếu bạn gặp lỗi Invariant Violation: new NativeEventEmitter() requires a non-null argument, hãy đảm bảo đã cài đặt tất cả dependencies bắt buộc và chạy:

# iOS
cd ios && pod install && cd ..

# Xóa cache và rebuild
cd ios && rm -rf build Pods Podfile.lock && pod install && cd ..

Lỗi Build

1. Xóa cache:

# React Native
npx react-native start --reset-cache

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

# Android
cd android && ./gradlew clean && cd ..

2. Cài đặt lại dependencies:

rm -rf node_modules yarn.lock package-lock.json
npm install # hoặc yarn install

Lỗi TypeScript

Đảm bảo bạn đã cài đặt đúng các TypeScript types:

npm install --save-dev @types/react @types/react-native @types/crypto-js

Lỗi Vector Icons không hiển thị

Nếu icons không hiển thị:

# Chạy lại react-native-asset
npx react-native-asset

# Hoặc rebuild app
# iOS
cd ios && pod install && cd ..
npx react-native run-ios

# Android
npx react-native run-android

API Documentation

Để xem tài liệu API chi tiết, vui lòng tham khảo INSTALLATION.md.

Ứng dụng Ví dụ

SDK bao gồm một ứng dụng example đầy đủ để minh họa tất cả các tính năng:

# Clone repository
git clone https://github.com/skyfi-dongnh/SkyFi-SDK-RN.git
cd SkyFi-SDK-RN

# Cài đặt dependencies
yarn install

# Chạy ứng dụng example
cd example

# iOS
yarn ios

# Android
yarn android

Đóng góp

Xem CONTRIBUTING.md để biết hướng dẫn đóng góp.

Hỗ trợ

• 📧 Email: [email protected]
• 🐛 Báo lỗi: GitHub Issues
• 📖 Tài liệu: GitHub Wiki

Giấy phép

MIT © SkyFi Team

Được tạo với ❤️ sử dụng create-react-native-library