> This page is for Da videocamera a cloud.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.
# Architettura di integrazione
## Introduzione
Prima di iniziare a fare delle richieste API, devi comprendere l'architettura di base delle integrazioni C2C. Non preoccuparti: nel prossimo articolo lavorerai nel terminale. Per ora, esaminiamo questi concetti essenziali.
Il modello dati semplificato per l'integrazione sarà simile a questo:
```text
┌───────────────────┐ ┌─────────┐
│ Project Device 01 │ -> │ Project │
┌───────────┐ ┌──────────────┐ └───────────────────┘ └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘ └──────────────┘ ┌───────────────────┐ ┌─────────┐
│ Project Device 02 │ -> │ Project │
└───────────────────┘ └─────────┘
```
## App OAuth
L'integrazione è definita da un'app OAuth, ovvero un'entità registrata con il nostro backend che consente ai dispositivi di autorizzarsi con Frame.io utilizzando [OAuth 2](https://oauth.net/2/). L'app OAuth definisce la strategia di autorizzazione per l'intera integrazione. Ogni dispositivo che gli utenti connettono a Frame.io viene autorizzato tramite la stessa app OAuth (anche se gli integratori con più linee di dispositivi potrebbero voler usare una singola app OAuth per ogni linea).
Per le integrazioni C2C, utilizziamo un flusso OAuth specializzato e progettato specificatamente per dispositivi con capacità di interfaccia utente limitate.
### Autenticazione per dispositivi C2C
L'API C2C è progettata per dispositivi con capacità di interfaccia utente limitate. Questi dispositivi consentono a un utente di connetterli a Frame.io mediante la visualizzazione di un codice a 6 cifre, che l'utente inserisce poi sul sito web Frame.io utilizzando il proprio browser.
Ai dispositivi viene rilasciato un `client_secret` che deve essere fornito al nostro backend per ricevere un codice di autorizzazione a 6 cifre. Questo approccio semplificato garantisce un'esperienza di autenticazione coerente e sicura in tutte le integrazioni C2C.
## Modelli di dispositivo
Il modello di dispositivo configura il comportamento del dispositivo durante l'interazione con il backend C2C, incluse le funzionalità supportate. Le seguenti impostazioni sono configurate dal modello di dispositivo:
Indica se l'integrazione utilizza dei socket a bassa latenza per comunicare il proprio stato corrente oppure delle chiamate REST con latenza superiore.
Il nome dell'integrazione come deve apparire nel percorso di qualsiasi risorsa caricata.
C2C consente di caricare risorse solo in percorsi file root specifici, ma al di sotto di questo requisito il dispositivo può essere configurato per caricare risorse in un percorso file calcolato dinamicamente in base ai metadati forniti della risorsa.
Indica quali metadati saranno obbligatori quando carichi una risorsa su Frame.io, soprattutto per supportare il percorso file tokenizzato.
Indica se l'integrazione utilizza dei socket a bassa latenza per comunicare il proprio stato corrente oppure delle chiamate REST con latenza superiore.
Le funzionalità supportate dal dispositivo possono cambiare nelle diverse versioni del firmware. Per abilitare la compatibilità con le versioni precedenti e offrire un'esperienza utente fluida, la configurazione del dispositivo viene selezionata dinamicamente in base alla versione del firmware rilevata. Nel prossimo futuro, un'integrazione potrà avere più di un DeviceModel. Il modello di dispositivo da utilizzare verrà determinato confrontando la versione del firmware del dispositivo con il requisito della versione minima del firmware di un modello di dispositivo specifico.
## Dispositivi di progetto e identificazione
Il `ProjectDevice` rappresenta ogni istanza fisica di un dispositivo collegato a Frame.io. Un `ProjectDevice` si identifica utilizzando un valore di identificazione univoco chiamato `client_id`. Questo valore dovrebbe essere qualcosa che sicuramente non verrà condiviso tra due dispositivi. Può essere il numero di serie di un dispositivo o una stringa casuale che il dispositivo ha generato una volta e ha poi salvato. Il `client_id` NON dovrebbe essere un valore che il tuo dispositivo non possiede, come l'indirizzo MAC di un computer.
Il nostro backend tiene traccia di ogni dispositivo di progetto e salva le rispettive informazioni, come la versione del firmware attuale.
A ogni `ProjectDevice` sarà associato un `project` Frame.io specifico e un'`OauthAuthorization` che concede al dispositivo accesso al progetto e un insieme di ambiti che dettagliano cosa un dispositivo può fare. Per maggiori informazioni sugli ambiti disponibili, consulta le guide dettagliate sull'implementazione dell'autenticazione e dell'autorizzazione. Il `ProjectDevice` è il valore che viene restituito dall'endpoint `/me`. Un `dispositivo` può essere collegato attivamente solo a un singolo `ProjectDevice` alla volta, perciò a un singolo `progetto` alla volta.
## Versioni firmware
Il tuo dispositivo deve fornire la sua versione firmware attuale con l'intestazione HTTP `x-client-version` ogni volta che chiami un endpoint su `https://api.frame.io`. Le prossime guide API includeranno questa intestazione in ogni esempio. In alcuni casi, il nostro backend deve ordinare più versioni firmware. Per farlo, richiediamo che i valori siano OBBLIGATORIAMENTE una [versione semantica](https://semver.org/) valida. Tra gli altri, sono inclusi valori come `0.1.2`, `2.1.3-preview.01` e `2.1.3-preview.01+build_19770504.01`.
Viene restituito un errore se i valori della versione del firmware non sono versioni semantiche valide. Comprendiamo che non tutte le integrazioni tengono traccia del firmware utilizzando il controllo delle versioni semantico e, in questi casi, chiediamo di tenere traccia di una versione semantica da fornire al nostro backend per ogni versione interna che viene creata.
Fornendo l'intestazione, release diverse del firmware possono supportare funzionalità diverse (e talvolta contrastanti) all'interno di Frame.io.
La versione del firmware viene gestita solo dalle chiamate a https://api.frame.io; quando si effettuano chiamate a https://applications.frame.io, l'intestazione non ha alcun effetto.
L'intestazione HTTP `x-client-version` è ora obbligatoria e verrà applicata dai server di Frame.
## Passaggi successivi
È il momento di effettuare alcune chiamate API! Scopriamo come eseguire l'autenticazione e l'autorizzazione con C2C. Segui la [guida di configurazione](./implementing-c2c-setting-up) per iniziare.