Chaindoc logoChaindoc

Paigaldus

Lisage Chaindoc SDK-d oma projekti. On kaks paketti: Server SDK tagatöödeks (dokumendid, allkirjad, verifitseerimine) ja Embed SDK allkirjastamise liidese integreerimiseks frontend-i.

Enne alustamist

Kui teil pole veel kontot, alustage kiirjuhendist, et see seadistada.

Server SDK

Server SDK haldab kõiki tagatoiminguid: dokumentide loomine, allkirjataotluste saatmine, meeskondade haldamine ja blockchain verifitseerimise käivitamine. See on õhuke ümbris REST API ümber, nii et kui olete API dokumentatsiooni lugenud, tunduvad meetodite nimed tuttavad.

Paketi paigaldamine

npm install @chaindoc_io/server-sdk

Keskkonnamuutujate seadistamine

Looge oma projekti juurkausta `.env` fail. Siin vajate oma salajast võtit.

.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

SDK lähtestamine

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

Põhikonfiguratsioon on enamike projektide jaoks piisav. Uuesti proovimise seaded on mõistlik häälestada, kui töödeldate palju dokumente partii kaupa, kuna API-l on rate limit-id.

Ühenduse verifitseerimine

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

Kui see ebaõnnestub, kontrollige, et teie salajane võti algab `sk_live_` (tootmine) või `sk_test_` (sandbox). Kõige levinum probleem on juhuslikult avaliku võtme kasutamine.

Embed SDK

Embed SDK võimaldab teil kuvada Chaindoc allkirjastamise liidest oma veebirakenduses. Teie kasutajad allkirjastavad dokumente lahkumata teie saidilt. See töötab React, Vue, Angular või puhta JavaScript-iga.

Paketi paigaldamine

npm install @chaindoc_io/embed-sdk

CDN valik on mugav kiireks prototüüpimiseks või saitidele ilma build sammuta. Tootmiseks kasutage npm paketti, et saada tree-shaking ja korralik versioonikontroll.

Keskkonnamuutujate seadistamine

Embed SDK kasutab teie avalikku võtit (`pk_`), mida on ohutu lisada kliendipoolsesse koodi.

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

Rakenduse lähtestamine

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

Raamistiku-spetsiifiline seadistus

Need näited näitavad, kuidas siduda Embed SDK pakkuja või teenusena igas raamistikus. Kui kasutate Server SDK-d tagapoolses süsteemis, ei ole pakkuja vaja; lihtsalt importige see seal, kus vajate.

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

TypeScript konfiguratsioon

Mõlemad SDK-d sisaldavad täielikke TypeScript definitsioone. Te ei vaja täiendavaid `@types` pakette.

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

Kui kasutate vanemat TypeScript seadistust (< 5.0), kasutage `"moduleResolution": "node"` asemel `"bundler"`.

Arendus vs tootmine

Kasutage arenduses testvõtmeid, et te ei loeks juhuslikult päris dokumente ega saadaks allkirjade emaile tegelikele saajatele.

Arenduse seadistus

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

Lipp `debug: true` prindib päringute/vastuste detailid konsooli. See on müra täis, kuid kasulik, kui mõistate, miks midagi ei tööta.

Tootmise seadistus

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

Paigalduse verifitseerimine

Järgige neid kontrolle, et veenduda, et kõik on õigesti ühendatud:

1Kontrollige SDK versiooniKäivitage `console.log(ChaindocEmbed.version)` oma rakenduses. Kui see prindib versiooninumbri, on pakett õigesti paigaldatud.

2Testige API ühendustKutsuge `chaindoc.healthCheck()` oma tagasüsteemist. Edukas vastus tähendab, et teie salajane võti on kehtiv ja API on kättesaadav.

3Proovige faili üleslaadimistLaadige üles väike test PDF kasutades `chaindoc.media.upload()`. See kinnitab, et autentimine, võrgundus ja failide käsitlemine kõik töötavad.

4Avage allkirjastamise liidesLähtestage Embed SDK ja kutsuge `openSignatureFlow()` test sessiooniga. Kui modaalne aken ilmub, olete valmis.

Troubleshooting

"Module not found" viga

See tavaliselt tähendab, et pakett ei paigaldanud korralikult või on vahemällu salvestatud versiooni konflikt. Tühjendage kõik ja paigaldage uuesti:

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

TypeScript tüübivead

Veenduge, et teil on Node.js tüübid paigaldatud ja teie `tsconfig.json` kasutab õiget mooduli lahendust. Enamik probleeme pärineb mittesobivatest `moduleResolution` seadetest.

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

API võtme vead

Kui saate 401 või 403 vastuseid, siis kontrollige järgmist:

  • 401 Unauthorized tähendab, et võti on kehtetu või aegunud. Genereerige see oma dashboard-is uuesti.
  • 403 Forbidden tähendab, et teie plaan ei sisalda API ligipääsu. Teil on vaja Business plaani.
  • Veenduge, et kasutate õiget võtmetüüpi: `pk_` võtmed on Embed SDK jaoks (frontend), `sk_` võtmed on Server SDK jaoks (backend). Nende segamine on kõige levinum viga.
  • Testvõtmed (`_test_`) töötavad ainult sandbox-is. Live võtmed (`_live_`) suunavad tootmisesse.

Mis edasi?

Nüüd, kui SDK-d on paigaldatud, valige oma järgmine samm: