> This page is for Piattaforma, version Versione precedente.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt

> 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.

# Guida pratica: Autorizzazione (hardware)

## Introduzione

In questa guida imparerai ad autenticare e autorizzare un dispositivo hardware Camera to Cloud (C2C) su un progetto [Frame.io](http://frame.io/). Illustreremo sia il metodo di associazione tradizionale mediante inserimento manuale del codice sia il nuovo metodo di associazione mediante codice QR per migliorare l'esperienza utente.

## Cosa serve?

Se non hai letto la guida [Prima di iniziare l'implementare](link), dalle un'occhiata veloce prima di proseguire. Inoltre, dovresti aver ricevuto dal nostro team un `client_secret` che sarà utilizzato per identificare la tua integrazione. Se non hai ricevuto un `client_secret`, leggi [questa introduzione](LINK) all'ecosistema C2C e contatta il nostro team.

### Prerequisiti per l'associazione mediante codice QR





Prima di iniziare con l'associazione mediante codice QR, assicurati che siano soddisfatti i seguenti prerequisiti:





* **Attivazione del flag di funzione**: un flag di funzione specifico (`v4.c2c_qr_code_activate`) deve essere abilitato nel tuo account [Frame.io](http://frame.io/). Questo flag di funzione consentirà l'accesso al metodo di associazione basato su codice QR. Il referente designato di [Frame.io](http://frame.io/) ti aiuterà ad attivare questa funzione per l'account che scegli.
* **Compatibilità della fotocamera**: assicurati che l'hardware della fotocamera sia aggiornato per supportare la generazione di codici QR durante il processo di associazione del dispositivo.




## Guida al flusso di autorizzazione hardware





Assicuriamoci di avere una comprensione generale dell'esperienza utente prevista per il flusso di autorizzazione che vogliamo implementare. Consulta le seguenti risorse per vedere questo flusso dal punto di vista dell'utente:





* Articolo dell'assistenza sulla procedura per aggiungere nuovi dispositivi hardware.
* Video didattico su come autorizzare un Teradek Cube.




Il flusso di autorizzazione hardware è progettato per alleggerire il più possibile il lavoro di chi esegue l'implementazione e, di conseguenza, l'interfaccia utente del dispositivo. Con questo flusso non dovrai preoccuparti di:





* Reindirizzare a un browser.
* Gestire l'accesso e l'autenticazione utente a [Frame.io](http://frame.io/).
* Elencare e selezionare l'account e il progetto a cui connettersi.
* Elementi dell'interfaccia utente oltre alle visualizzazioni di informazioni di base.




### Migliorare l'esperienza utente con l'associazione mediante codice QR





Data la crescente richiesta di efficienza e facilità d'uso, gli utenti si aspettano sempre più che le interazioni con i propri dispositivi siano fluide. Il processo attuale per associare le fotocamere al servizio C2C di Frame.io richiede diversi passaggi, incluso l'inserimento manuale di un codice di associazione. Pur essendo funzionale, questo processo può essere semplificato.





Sfruttando i codici QR (un po' come accade per l'associazione dei dispositivi per servizi di streaming come Netflix o Disney+) possiamo semplificare il processo, eliminare errori causati dall'inserimento manuale e ridurre il tempo necessario per associare una fotocamera.






## Identificazione del dispositivo (client_id)





Al momento di connettersi a Camera to Cloud, ogni dispositivo hardware fisico deve identificarsi in modo univoco affinché sia possibile elencare le connessioni dei dispositivi nel progetto di un utente.

Per i dispositivi hardware, questo è il `client_id` del dispositivo, a seconda del modello di autorizzazione che scegli di utilizzare. Quando configuri l'implementazione, devi pensare a come farlo. Potresti utilizzare un numero di serie del dispositivo hardware, un UUID o una stringa identificativa univoca. Fai attenzione a non divulgare informazioni di identificazione personale. L'e-mail dell'utente, ad esempio, non è un valore valido da utilizzare come `client_id`.

Allo stesso modo, assicurati di possedere l'identificatore univoco. Se stai implementando l'API C2C come dispositivo software, non utilizzare l'indirizzo MAC del dispositivo, ad esempio. L'indirizzo MAC non è di proprietà del tuo software e potrebbe anche essere considerato un'informazione di identificazione personale.





Se non sei sicuro del valore che vorresti utilizzare, possiamo discutere insieme questa scelta e assicurarci che venga scelto un valore adatto, in grado di semplificare il più possibile l'integrazione.






## Passaggio 1: richiedi un codice dispositivo

Iniziamo con l'implementazione. La prima cosa che dobbiamo fare è richiedere un codice dispositivo da fornire all'utente per un dispositivo. Per farlo, occorre chiamare l'endpoint `/v2/auth/device/code`:

### Metodo di associazione tradizionale





```
curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool
```







### Abilitazione dell'associazione mediante codice QR





Per abilitare l'associazione basata su codice QR, è necessaria una piccola modifica nella chiamata API. In particolare, è necessario aggiungere due nuove intestazioni alla richiesta del codice dispositivo. Ciò consente ai dispositivi di collegarsi direttamente alla pagina di associazione e semplificare il processo di associazione.






```
curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool
```

**Nota:** stiamo utilizzando dati del modulo, invece di dati JSON. Gli endpoint di autenticazione C2C accettano solo dati di modulo. Una volta effettuata l'autenticazione, gli altri endpoint accetteranno i payload JSON, ma gli endpoint di autenticazione restituiranno un errore se vengono inviati payload JSON.

#### Parametri payload




* **client_id**: un identificatore univoco per il dispositivo hardware fisico. Questo valore deve essere garantito come univoco per il dispositivo. Potrebbe essere un numero di serie o un UUID generato casualmente.
* **client_secret**: verrà rilasciato dall'assistenza [Frame.io](http://frame.io/) e identifica il modello del dispositivo. Questo valore non deve essere divulgato all'utente e deve essere crittografato quando non è in uso.
* **scope**: le autorizzazioni che stiamo richiedendo; gli spazi vengono utilizzati come delimitatori. I dispositivi hardware possono richiedere solo i seguenti due ambiti:
* `asset_create`: consente al dispositivo di creare e caricare risorse.
* `offline`: consente al dispositivo di aggiornare la propria autorizzazione utilizzando un token di aggiornamento. I token di autorizzazione scadono dopo 8 ore perciò, senza questo ambito, l'utente dovrebbe autorizzare nuovamente il dispositivo ogni 8 ore.




In pratica, i dispositivi vorranno quasi sempre richiedere entrambi gli ambiti.






### Informazioni sulla risposta API





Quando effettuiamo la richiesta, otteniamo una risposta simile alla seguente:






#### Risposta di associazione tradizionale





```
{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}
```







#### Risposta di associazione mediante codice QR





```
{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}
```







#### Spiegazione della risposta




* **device_code**: il codice del dispositivo deve essere nascosto all'utente e serve per identificare questa richiesta di autorizzazione durante il polling per verificare se l'utente ha inserito correttamente il codice.
* **expires_in**: il numero di secondi prima della scadenza di questo codice.
* **interval**: quanto tempo deve attendere l'utente tra le richieste di polling per verificare se ha inserito il codice.
* **name**: il nome del dispositivo che si sta cercando di connettere.
* **user_code**: il codice a sei cifre che l'utente inserirà in [Frame.io](http://frame.io/) per associare il dispositivo a un progetto.
* **verification_uri**: questo è l'URL che gli utenti inseriranno manualmente nel caso in cui il codice QR non venga scansionato. Dovrebbe essere conciso e facile da ricordare.
* **verification_uri_complete**: questo URL contiene il codice di associazione ed è destinato alla trasmissione non testuale (ad esempio, il codice QR). Una volta scansionato, indirizza automaticamente l'utente all'esperienza di associazione per scegliere un account e un progetto a cui connettere il dispositivo.




### Mostrare il codice QR all'utente

Dopo aver ottenuto `verification_uri_complete`, è possibile generare un codice QR da questo URL e mostrarlo all'utente sullo schermo del dispositivo. Ciò permette all'utente di scansionare semplicemente il codice QR con il dispositivo mobile o la fotocamera, semplificando il processo di associazione.

#### Esempio: schermata della fotocamera con codice QR visualizzato





*Inserisci l'immagine o l'illustrazione di una schermata della fotocamera che mostra il codice QR.*

Se l'utente non può scansionare il codice QR per qualsiasi motivo, occorre mostrare anche `user_code` e `verification_uri` in modo che possa inserire manualmente il codice di associazione. In alternativa, puoi anche mostrare `verification_uri` come codice QR statico che l'utente può scansionare con i dispositivi mobili. Se l'integrazione è un'app su dispositivo mobile, è obbligatorio mostrare `verification_uri_complete` come link ipertestuale che gli utenti possono toccare per facilitare la connettività, dato che l'utente non può scansionare il codice QR con il dispositivo su cui si trova l'applicazione.

## Passaggio 2: polling dell'autorizzazione utente





Una volta consegnato il codice di associazione o aver mostrato il codice QR all'utente, occorre verificare se l'ha inserito. Per farlo, possiamo effettuare la seguente richiesta:






```
curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool
```







### Parametri payload




* **client_id**: lo stesso `client_id` inviato nel passaggio 1.
* **device_code**: il `device_code` restituito da `/v2/auth/device/code`.
* **grant_type**: il tipo di concessione dell'autorizzazione che il sistema OAuth sta rilasciando. Questo valore sarà sempre `urn:ietf:params:oauth:grant-type:device_code`.




Le prime volte che viene effettuata questa richiesta, probabilmente si otterrà una risposta di questo tipo:






```
{
  "error": "authorization_pending"
}
```






Non c'è problema! Non si tratta di un errore irreversibile. Significa semplicemente che l'utente non ha ancora inserito il codice utente nella UI di Frame.io. Occorre semplicemente continuare il polling fino a quando non l'ha fatto.





Se, invece, compare un errore come questo:






```
{
  "error": "expired_token"
}
```






Significa che il codice è scaduto prima che l'utente potesse inserirlo. In questo caso, occorre generare un nuovo codice di associazione o codice QR utilizzando il passaggio 1, mostrarlo all'utente e quindi riprendere il polling.





Alla fine, la risposta dovrebbe essere questa:






```
{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}
```






Se il payload della risposta ha questo aspetto: complimenti! Hai autorizzato il tuo primo dispositivo Camera to Cloud. È il momento di festeggiare!





Adesso però diamo un'occhiata al payload di risposta per comprenderlo:





* **access_token**: questa è la tua chiave per il resto del backend [Frame.io](http://frame.io/). Dovrà essere aggiunto all'intestazione delle altre richieste che faremo in queste esercitazioni.
* **expires_in**: il numero di secondi fino alla scadenza di `access_token`. Una volta scaduto il token, dovrà essere aggiornato. Tratteremo questo argomento in un'esercitazione futura.
* **refresh_token**: un token che possiamo utilizzare per gestire il nostro `access_token`. Verrà utilizzato principalmente per aggiornare l'autorizzazione, ma può anche essere utilizzato per revocarla.
* **token_type**: sarà sempre `bearer` per l'API C2C e non è operativo.




## Abbinamento dei passaggi





Ora che sappiamo quali chiamate che dobbiamo effettuare, uniamole in uno pseudocodice in stile Python. Ricorda: è possibile che il codice del dispositivo scada, quindi occorre gestire questa possibilità quando si configura la logica:






**`Python`**

```python title="Python"
def authorize_with_frame():
    """
    Handles authorizing our device with Frame.io.
    """

    # Our client ID can be a serial number, UUID, or some other unique string.
    client_id = THIS_DEVICE.get_serial_number()

    while True:
        # Make the call to Frame.io to get our device codes.
        pairing_codes = c2c.get_device_codes(client_id)

        # We need to keep track of how long we have been polling for
        polling_started = datetime.now()

        # Now we are going to poll for authorization until the user enters the code.
        while True:

            # Re-write this output each time we poll. Note: This message will only update once
            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
            # need a different implementation.
            print(
                f"\rPAIRING CODE: {pairing_codes.user_code}, "
                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
            )

            # Wait for `interval` before polling each time.
            sleep(pairing_codes.interval)

            # Make a call to Frame.io to see if the user has entered the code and authorized
            # the device.
            authorization, error = c2c.poll_for_authorization(
                client_id, pairing_codes.device_code
            )

            if error and error.message == "authorization_pending":
                # If the authorization is pending, try again.
                continue
            elif error and error.message == "expired_token":
                # If the pairing codes have expired, break to generate new codes.
                break
            elif error:
                # If we get another error, we should raise it. (advanced error handling will
                # be covered in another tutorial)
                raise Exception(error.message)

            return authorization
```

**Nota:** in questo pseudocodice abbiamo aggiunto un ciclo esterno per gestire il caso in cui i codici di abbinamento scadano e dobbiamo richiederne di nuovi. L'ultima cosa che dovremmo fare è recuperare le informazioni sul progetto a cui ci siamo connessi da [Frame.io](http://frame.io/) e mostrarle all'utente per confermare ulteriormente che il dispositivo è stato associato al progetto previsto. Vedremo come farlo nell'esercitazione successiva.

## Risoluzione dei problemi





Se sei qui, allora qualcosa è andato storto! Cosa sarebbe l'integrazione con una terza parte senza qualche tipo di errore? Questa sezione elenca una serie di problemi comuni e ti guida attraverso i passaggi più probabili per risolverli. Dai un'occhiata all'elenco in basso e controlla se qualcosa corrisponde al problema che stai riscontrando.





Se non trovi una soluzione qui, ci farebbe molto piacere conoscere il problema che hai riscontrato per poterlo aggiungere in questa sezione.





* **Non vedo un pulsante "Connetti dispositivo"**: se vai al pannello di gestione C2C e non vedi un pulsante "Connetti dispositivo", si sta verificando una di queste due situazioni:
* ~~**C2C non è attivato per il tuo account**: se la schermata è vuota e compare un messaggio che dice che C2C non è disponibile per il tuo account, il gestore dell'account deve attivarlo per il tuo progetto nelle impostazioni dell'account.~~
* **Non sei un gestore del dispositivo**: se la schermata è vuota e compare un messaggio che dice che non hai le autorizzazioni, il gestore dell'account deve cambiare le autorizzazioni per stabilire chi può connettere i dispositivi C2C oppure aggiungerti a un ruolo che ha quelle autorizzazioni.
* **Hai già un dispositivo connesso**: dopo aver connesso il primo dispositivo, il pulsante blu "Aggiungi nuovo dispositivo" scompare e devi accedere al menu con tre puntini in alto a destra del pannello Connessioni C2C.
* **Errore di client non valido**: viene restituito `invalid_client` quando le informazioni che ci stai fornendo sul dispositivo non corrispondono a quelle registrate. È molto probabile che il tuo `client_secret` non sia corretto.
* **Errore di richiesta non valida**: viene restituito `bad_request` quando i dati della richiesta sono in un formato errato. Controlla di non aver scritto male il nome di un campo o di non aver dimenticato di aggiungere un campo obbligatorio.




## Avanti





Se non l'hai già fatto, ti incoraggiamo a contattare il nostro team, poi continua con la guida successiva: [LINK](). A presto!





* * *





## Parcheggio





Da fare




Aggiungere una soluzione alternativa ai partner che non possono generare un codice QR dinamico,

ovvero mostra "Vai a `**verification_uri**` per inserire questo codice" come piano di riserva