Chaindoc logoChaindoc

Cài đặt

Hướng dẫn cài đặt đầy đủ cho SDK Chaindoc. Cài đặt SDK Server cho tích hợp phía máy chủ và SDK Embed cho giao diện ký kết phía người dùng.

Điều kiện tiên quyết

Cài đặt SDK máy chủ

Server SDK được sử dụng cho tích hợp phía máy chủ - quản lý tài liệu, yêu cầu ký tên và xác minh blockchain.

Bước 1: Cài đặt gói

npm install @chaindoc_io/server-sdk

Bước 2: Cấu hình biến môi trường

Tạo tệp .env trong thư mục gốc của dự án:

.env
# Production keys
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Staging/Testing keys
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Optional: Custom API endpoint
# CHAINDOC_API_URL=https://api.chaindoc.io

Bước 3: Khởi tạo SDK

lib/chaindoc.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

// Basic initialization
export const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Optional
  timeout: 60000, // 60 seconds
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

Bước 4: Kiểm tra kết nối

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('✓ Connected to Chaindoc API');
  console.log('User ID:', health.userId);
} else {
  console.error('✗ Connection failed');
}

Cài đặt SDK nhúng

SDK nhúng cung cấp giao diện ký tên cho các ứng dụng web. Hoạt động với bất kỳ khung JavaScript nào.

Bước 1: Cài đặt gói

npm install @chaindoc_io/embed-sdk

Bước 2: Cấu hình biến môi trường

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Bước 3: Khởi tạo trong ứng dụng của cậu

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
      environment: 'production',
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return sdkRef.current;
}

Cài đặt cụ thể cho khung làm việc

Next.js (App Router)

app/providers.tsx
'use client';

import { createContext, useContext, useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    if (!sdkRef.current) {
      sdkRef.current = new ChaindocEmbed({
        publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
      });
    }

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js (Pages Router)

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return <Component {...pageProps} />;
}

Nuxt 3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

Angular

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

Cấu hình TypeScript

Cả hai SDK đều bao gồm định nghĩa TypeScript đầy đủ. Không cần cài đặt thêm gói @types.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Cấu hình môi trường

Môi trường phát triển

terminal
// Use test keys for development
const chaindoc = new Chaindoc({
  secretKey: 'sk_test_xxxxx',
  baseUrl: 'https://api.chaindoc.io',
});

const embed = new ChaindocEmbed({
  publicKey: 'pk_test_xxxxx',
  environment: 'staging',
  debug: true, // Enable detailed logs
});

Môi trường sản xuất

terminal
// Use live keys for production
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!, // sk_live_xxxxx
});

const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!, // pk_live_xxxxx
  environment: 'production',
});

Xác minh

Kiểm tra cài đặt của cậu bằng các bước xác minh sau:

1Kiểm tra phiên bản SDKconsole.log(ChaindocEmbed.version); // Nên hiển thị số phiên bản

2Xác minh kết nối APIKiểm tra điểm cuối kiểm tra sức khỏe để xác nhận các khóa API là hợp lệ

3Tải lên tệp thử nghiệmTải lên một tệp thử nghiệm nhỏ để kiểm tra xem các điểm cuối truyền thông có hoạt động không.

4Khởi tạo SDK nhúngKhởi tạo SDK và kiểm tra bảng điều khiển trình duyệt để phát hiện lỗi (nếu có).

Khắc phục sự cố

Lỗi không tìm thấy mô-đun

terminal
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# For yarn
rm -rf node_modules yarn.lock
yarn install

Lỗi TypeScript

Nếu cậu gặp lỗi TypeScript, hãy đảm bảo tệp tsconfig.json của cậu có cài đặt giải quyết mô-đun chính xác và các loại Node.js đã được cài đặt.

terminal
npm install --save-dev @types/node

Vấn đề về API Key

Các bước tiếp theo

  • Xem lại Hướng dẫn Bắt đầu Nhanh cho lần tích hợp đầu tiên của cậu.
  • Kiểm tra tài liệu API để tham khảo endpoint.
  • Tham khảo tài liệu SDK để tìm hiểu các tính năng nâng cao.
  • Cài đặt Webhooks để nhận thông báo thời gian thực
  • Tham gia cộng đồng phát triển trên GitHub để nhận hỗ trợ