Chaindoc logoChaindoc

Встановлення

Повна інструкція з установки Chaindoc SDK. Налаштуйте Server SDK для інтеграції бекенду та Embed SDK для інтерфейсу підпису фронтенду.

Необхідні умови

Встановлення SDK сервера

Server SDK використовується для інтеграції бекенду — управління документами, запити на підпис та перевірка блокчейну.

Крок 1: Встановити пакет

npm install @chaindoc_io/server-sdk

Крок 2: Налаштуйте змінні середовища

Створіть файл .env у кореневій папці вашого проєкту:

.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

Крок 3: Ініціалізація 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',
  },
});

Крок 4: Перевірка з'єднання

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');
}

Вбудована установка SDK

Embed SDK надає інтерфейс для підписання веб-додатків. Працює з будь-яким фреймворком JavaScript.

Крок 1: Встановити пакет

npm install @chaindoc_io/embed-sdk

Крок 2: Налаштуйте змінні середовища

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

Крок 3: Ініціалізація у вашому додатку

// 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;
}

Налаштування для конкретної платформи

Next.js (маршрутизатор додатків)

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();
  }
}

Конфігурація TypeScript

Обидва SDK містять повні визначення TypeScript. Додаткові пакети @types не потрібні.

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

Налаштування середовища

Середовище розробки

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
});

Виробниче середовище

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',
});

Перевірка

Перевірте свою інсталяцію за допомогою таких кроків:

1Перевірте версію SDKconsole.log(ChaindocEmbed.version); // Повинен вивести номер версії

2Перевірка з'єднання APIПеревірте кінцеву точку перевірки працездатності, щоб підтвердити дійсність ключів API

3Завантаження тестового файлуЗавантажте невеликий тестовий файл, щоб перевірити роботу кінцевих точок медіа

4Ініціалізуйте Embed SDKІніціалізуйте SDK і перевірте консоль браузера на наявність помилок

Усунення несправностей

Помилка «Модуль не знайдено»

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

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

Помилки TypeScript

Якщо ви бачите помилки TypeScript, переконайтеся, що у вашому файлі tsconfig.json вказані правильні налаштування роздільної здатності модулів і встановлені типи Node.js.

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

Проблеми з API-ключем

Наступні кроки

  • Ознайомтеся з коротким посібником для початківців, щоб виконати першу інтеграцію
  • Перевірте документацію API для посилання на кінцеву точку
  • Ознайомтеся з документацією SDK для розширених функцій
  • Налаштуйте веб-хуки для сповіщень у реальному часі
  • Приєднуйтесь до спільноти розробників на GitHub для отримання підтримки