@doraverse/cookie-consent

Cookie consent component cho các ứng dụng Doraverse với tích hợp API tracking và quản lý permissions.

Cài đặt

pnpm add @doraverse/cookie-consent

Sử dụng

Setup cơ bản

Wrap ứng dụng của bạn với CookieConsentProvider:

import { CookieConsentProvider } from '@doraverse/cookie-consent';

function App() {
  return (
    <CookieConsentProvider 
      // baseUrl là tùy chọn. Nếu không truyền, package sẽ tự suy luận theo domain
      // baseUrl="https://auth.doradora.vn"
      lang="en" // 'vi' | 'en' | 'ja'
    >
      {/* Rest of your app */}
    </CookieConsentProvider>
  );
}

export default App;

Sử dụng hook để check permissions / khởi tạo GA

import { useEffect } from 'react';
import { useCookieSettings } from '@doraverse/cookie-consent';

function MyComponent() {
  const { permissions, initGA, openSettings } = useCookieSettings();

  useEffect(() => {
    // Chỉ init GA khi backend bật GA và user cho phép analytics
    if (initGA && permissions?.analytics) {
      initGAClient();
    }
  }, [initGA, permissions?.analytics]);

  return (
    <div>
      <button onClick={openSettings}>Cookie Settings</button>
    </div>
  );
}

Ghi chú về baseUrl (tự suy luận)

• Không bắt buộc truyền baseUrl. Package sẽ tự suy luận khi chạy trên trình duyệt:
  • Domain chứa localhost hoặc doradora.vn -> dùng https://auth.doradora.vn
  • Domain chứa doradora.ai -> dùng https://auth.doradora.ai
  • Domain chứa doraverse.com -> dùng https://auth.doraverse.com
• Nếu không khớp các domain trên và không truyền baseUrl -> baseUrl = null và UI cookie consent sẽ không được render (tắt tính năng).

API

CookieConsentProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | baseUrl | string | auto-resolve | Base URL của API backend. Tùy chọn; sẽ tự suy luận theo domain như ghi chú trên | | lang | 'vi' \| 'en' \| 'ja' | 'en' | Ngôn ngữ hiển thị | | children | React.ReactNode | - | Nội dung ứng dụng |

useCookieSettings()

Hook để truy cập trạng thái cookie consent:

const {
  permissions,    // CookiePermissions - quyền hiện tại
  initGA,         // boolean - backend có bật GA không
  openSettings,   // () => void - mở popup settings
} = useCookieSettings();

CookiePermissions

interface CookiePermissions {
  necessary: boolean;    // Luôn true
  functional: boolean;   // Functional cookies
  analytics: boolean;    // Analytics cookies  
  marketing: boolean;    // Marketing cookies
}

API Endpoints

Package này tích hợp với API backend:

• GET {baseUrl}/api/v1/cookies-consent/status?version={packageVersion} - Lấy trạng thái consent
• POST {baseUrl}/api/v1/cookies-consent/tracking - Gửi thông tin consent

Build

# Build package
pnpm build

# Dev mode với watch
pnpm dev

# Type check
pnpm type-check

License

MIT © Doraverse