Chaindoc logoChaindoc

Installazione

Guida completa all'installazione degli SDK Chaindoc. Configura l'SDK Server per l'integrazione backend e l'SDK Embed per l'interfaccia di firma frontend.

Cosa ti serve

Installazione dell'SDK del server

L'SDK del server serve per l'integrazione del backend: gestione dei documenti, richieste di firma e verifica della blockchain.

Passaggio 1: Installa il pacchetto

npm install @chaindoc_io/server-sdk

Passaggio 2: configurare le variabili di ambiente

Crea un file .env nella directory principale del tuo progetto:

.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

Passaggio 3: avvia l'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',
  },
});

Passaggio 4: controlla la connessione

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

Installazione dell'SDK incorporato

L'SDK Embed offre un'interfaccia di firma per le app web. Funziona con qualsiasi framework JavaScript.

Passaggio 1: Installa il pacchetto

npm install @chaindoc_io/embed-sdk

Passaggio 2: configurare le variabili di ambiente

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

Passaggio 3: Inizia a usare la tua app

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

Configurazione specifica del framework

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)

pagine/_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

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

Configurazione TypeScript

Entrambi gli SDK hanno tutte le definizioni TypeScript. Non servono altri pacchetti @types.

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

Configurazione dell'ambiente

Ambiente di sviluppo

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

Ambiente di produzione

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

Verifica

Prova la tua installazione con questi passaggi di verifica:

1Controlla la versione dell'SDKconsole.log(ChaindocEmbed.version); // Dovrebbe mostrare il numero di versione

2Controlla la connessione APIProva l'endpoint di controllo dello stato per vedere se le chiavi API funzionano

3Carica file di provaCarica un piccolo file di prova per controllare che gli endpoint multimediali funzionino

4Inizializza Embed SDKAvvia l'SDK e controlla se ci sono errori nella console del browser.

Risoluzione dei problemi

Errore "Modulo non trovato"

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

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

Errori TypeScript

Se vedi errori TypeScript, controlla che il tuo tsconfig.json abbia le impostazioni giuste per la risoluzione dei moduli e che i tipi Node.js siano installati.

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

Problemi relativi alle chiavi API

Passi successivi

  • Dai un'occhiata alla guida rapida per la tua prima integrazione
  • Dai un'occhiata alla documentazione API per i riferimenti agli endpoint.
  • Dai un'occhiata alla documentazione degli SDK per le funzioni avanzate
  • Configura i webhook per ricevere notifiche in tempo reale
  • Entra nella community di sviluppatori su GitHub per avere supporto