Guida pratica: Autorizzazione | Frame.io API Documentation

Introduzione

Questa guida illustra il processo di autenticazione e autorizzazione per i dispositivi Camera to Cloud (C2C) su un progetto Frame.io. Esploreremo sia il metodo standard di inserimento manuale del codice sia l’approccio avanzato di associazione tramite codice QR per un’esperienza utente ottimale.

Cosa serve?

Esamina la guida introduttiva all’implementazione se non l’hai già fatto. Il nostro team dovrebbe averti fornito un client_secret per identificare la tua integrazione. In caso contrario, consulta questa introduzione all’ecosistema C2C e contatta il nostro team.

Prerequisiti per l’associazione mediante URL e codice QR

Per implementare l’associazione mediante URL e codice QR, assicurati di soddisfare questi requisiti:

Compatibilità del dispositivo: verifica che il dispositivo supporti la generazione di URL e codici QR durante il processo di associazione.

Guida al flusso di autorizzazione

Per comprendere il flusso di autorizzazione dal punto di vista dell’utente, consulta queste risorse:

Articolo dell’assistenza per aggiungere nuovi dispositivi.
Video didattico su come autorizzare un Teradek Cube.

Questo processo di autorizzazione riduce al minimo i requisiti di implementazione. Non è necessario:

Reindirizzare ai browser web (se non si usa l’associazione tramite codice URL)
Gestire l’autenticazione dell’utente Frame.io
Presentare interfacce per selezionare gli account o i progetti
Sviluppare componenti UI complessi oltre alle visualizzazioni di informazioni di base

Migliorare l’esperienza utente con l’associazione mediante codice URL

Gli utenti moderni si aspettano interazioni efficienti con i dispositivi. Benché l’attuale processo di associazione manuale funzioni adeguatamente, può essere ottimizzato.

Implementando l’associazione mediante URL e codice QR, così come accade per servizi di streaming come Netflix o Disney+, possiamo semplificare notevolmente il processo, ridurre al minimo gli errori di input e diminuire i tempi di associazione.

Identificazione del dispositivo (client_id)

Ogni dispositivo fisico richiede un identificatore univoco per il tracciamento della connessione all’interno del progetto di un utente.

Per i dispositivi, questo identificatore è il client_id, che è essenziale durante l’autorizzazione. Durante l’implementazione, prendi in considerazione le fonti appropriate per l’identificatore, ad esempio numeri di serie del dispositivo, UUID o altre stringhe univoche. Se stai eseguendo l’integrazione su un dispositivo Apple, ti consigliamo di usare un UUID persistente univoco che sia coerente anche dopo il riavvio del dispositivo. Fai attenzione alle informazioni di identificazione personale. Gli indirizzi e-mail degli utenti non sono valori appropriati per il client_id.

Inoltre, assicurati di controllare l’identificatore. Gli indirizzi MAC del dispositivo non sono adatti in quanto non sono di proprietà del tuo software e potrebbero costituire informazioni di identificazione personale.

Se hai bisogno di indicazioni per selezionare un identificatore appropriato, il nostro team può aiutarti a determinare un valore adatto che semplifichi l’integrazione.

Passaggio 1: richiedi un codice dispositivo

Per iniziare l’implementazione, richiedi un codice dispositivo tramite 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 URL

Per l’associazione con codice URL, modifica la chiamata API con intestazioni aggiuntive:

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 URL pairing
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Nota: questi endpoint di autenticazione accettano esclusivamente dati di modulo, non JSON. Dopo l’autenticazione, gli altri endpoint accetteranno i payload JSON, ma gli endpoint di autenticazione rifiuteranno le richieste JSON.

Parametri payload

client_id: l’identificatore univoco per il tuo dispositivo fisico. Deve essere univoco, ad esempio un numero di serie o UUID.
client_secret: fornito dall’assistenza di Frame.io per identificare il modello del tuo dispositivo. Questo valore riservato non deve essere accessibile dagli utenti e deve essere crittografato quando viene archiviato.
scope: le autorizzazioni richieste, separate da spazi. I dispositivi possono richiedere:
asset_create: abilita la creazione e il caricamento delle risorse. * offline: consente di aggiornare l’autorizzazione tramite un token di aggiornamento. Senza questo ambito, gli utenti dovrebbero autorizzare nuovamente il dispositivo ogni 8 ore alla scadenza dei token di autorizzazione.

Nelle implementazioni pratiche, i dispositivi richiedono solitamente entrambi gli ambiti.

Informazioni sulla risposta API

La richiesta genera una risposta simile a:

Risposta di associazione tradizionale

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

Risposta di associazione URL

{
  "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: questo identificatore interno deve rimanere nascosto agli utenti e identifica la richiesta di autorizzazione durante il polling.
expires_in: il periodo di validità del codice in secondi.
interval: l’intervallo di polling consigliato in secondi.
name: l’identificatore del dispositivo che si connette.
user_code: il codice a sei cifre per l’inserimento manuale in Frame.io per l’associazione del dispositivo.
verification_uri: l’URL di base per l’inserimento manuale quando la scansione QR non è disponibile.
verification_uri_complete: l’URL completo contenente il codice di associazione, da usare per creare un link ipertestuale all’interno di un’app mobile o per generare codici QR in modo da semplificare la navigazione dell’utente verso l’interfaccia di associazione.

Mostrare il codice QR all’utente

Usa verification_uri_complete per generare e visualizzare un codice QR sullo schermo del dispositivo affinché l’utente lo scansioni, in modo da consentire un’associazione efficiente.

Esempio: schermata del dispositivo con codice QR visualizzato

Esempio di schermata di associazione del dispositivo mediante codice QR Fornisci sempre opzioni delle opzioni alternative: visualizza user_code e verification_uri per l’inserimento manuale nei casi in cui la scansione QR non è possibile. In alternativa, valuta la possibilità di mostrare il verification_uri come codice QR statico per la scansione da dispositivo mobile. Per le integrazioni di app mobili, includi verification_uri_complete come link ipertestuale toccabile poiché gli utenti non possono scansionare codici QR dal dispositivo che esegue l’app.

Passaggio 2: polling dell’autorizzazione utente

Dopo aver fornito il codice di associazione o il codice URL, verifica il valore inserito dall’utente con questa 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 identificatore utilizzato nel passaggio 1.
device_code: il valore device_code restituito in precedenza.
grant_type: l’identificatore del tipo di concessione OAuth, che è sempre urn:ietf:params:oauth:grant-type:device_code per questa implementazione.

I tentativi di polling iniziali in genere restituiscono:

{
  "error": "authorization_pending"
}

Questo errore non irreversibile indica che l’utente non ha completato l’inserimento del codice. Continua il polling fino al completamento.

Nota per le app iOS: iOS: se l’utente passa all’app Frame.io per inserire il codice di associazione, la tua app potrebbe passare in background. Quando torna attiva, ad esempio tramite applicationDidBecomeActive, riprendi il polling in modo che il flusso di autorizzazione possa proseguire senza richiedere una nuova procedura di associazione.

Se ricevi:

{
  "error": "expired_token"
}

Il codice è scaduto prima dell’inserimento da parte dell’utente. Genera un nuovo codice o codice QR tramite il passaggio 1, mostralo all’utente e riprendi il polling.

Un’autorizzazione riuscita produce:

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

Complimenti per aver autorizzato il tuo dispositivo Camera to Cloud!

Esaminiamo questa risposta:

access_token: le tue credenziali di autenticazione per l’accesso al backend Frame.io, richieste nelle intestazioni per le future richieste API.
expires_in: il periodo di validità del token di accesso in secondi, dopo il quale è necessario l’aggiornamento.
refresh_token: utilizzato per la gestione del token di accesso, principalmente per l’aggiornamento dell’autorizzazione ma applicabile anche per la revoca.
token_type: è sempre bearer per le implementazioni dell’API C2C; non richiede alcuna azione.

Abbinamento dei passaggi

Ora implementiamo queste chiamate API in uno pseudocodice simile a Python, gestendo la potenziale scadenza del codice dispositivo:

Python

1 def authorize_with_frame():
2     """
3     Handles authorizing our device with Frame.io.
4     """
5 
6     # Our client ID can be a serial number, UUID, or some other unique string.
7     client_id = THIS_DEVICE.get_serial_number()
8 
9     while True:
10         # Make the call to Frame.io to get our device codes.
11         pairing_codes = c2c.get_device_codes(client_id)
12 
13         # We need to keep track of how long we have been polling for
14         polling_started = datetime.now()
15 
16         # Now we are going to poll for authorization until the user enters the code.
17         while True:
18 
19             # Re-write this output each time we poll. Note: This message will only update once
20             # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21             # need a different implementation.
22             print(
23                 f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                 f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25             )
26 
27             # Wait for `interval` before polling each time.
28             sleep(pairing_codes.interval)
29 
30             # Make a call to Frame.io to see if the user has entered the code and authorized
31             # the device.
32             authorization, error = c2c.poll_for_authorization(
33                 client_id, pairing_codes.device_code
34             )
35 
36             if error and error.message == "authorization_pending":
37                 # If the authorization is pending, try again.
38                 continue
39             elif error and error.message == "expired_token":
40                 # If the pairing codes have expired, break to generate new codes.
41                 break
42             elif error:
43                 # If there was some other error, raise it.
44                 raise error
45             else:
46                 # If there was no error, we have our authorization!
47                 return authorization
48 
49         # If we get here, our pairing codes expired. Let's try again.
50         print("\nPairing code expired. Generating a new one...")

Nota: l’outer loop gestisce i casi in cui i codici di associazione scadono e sono necessari nuovi codici.

Come passaggio finale, recupera e visualizza le informazioni del progetto da Frame.io per confermare che l’associazione al progetto previsto sia riuscito. Vedremo come farlo nell’esercitazione successiva.

Crea e visualizza codici QR per l’associazione

Durante l’implementazione dell’associazione tramite URL/codice QR, dovrai generare un codice QR dal valore verification_uri_complete nella risposta. Ecco alcuni esempi che utilizzano librerie popolari in diversi linguaggi di programmazione:

Esempio Python con qrcode

Python

1 import qrcode
2 from PIL import Image
3 import io
4 
5 def generate_qr_code(verification_uri_complete, size=250):
6     """
7     Generate a QR code from the verification_uri_complete URL.
8     
9     Args:
10         verification_uri_complete (str): The complete verification URI returned by Frame.io
11         size (int, optional): Size of the QR code in pixels. Defaults to 250.
12     
13     Returns:
14         PIL.Image: QR code image that can be displayed or saved
15     """
16     qr = qrcode.QRCode(
17         version=1,
18         error_correction=qrcode.constants.ERROR_CORRECT_L,
19         box_size=10,
20         border=4,
21     )
22     qr.add_data(verification_uri_complete)
23     qr.make(fit=True)
24     
25     img = qr.make_image(fill_color="black", back_color="white")
26     
27     # Resize the image if needed
28     img = img.resize((size, size))
29     return img
30 
31 # Example usage in authorization flow
32 def display_qr_for_pairing(pairing_codes):
33     """
34     Generate and display QR code along with manual pairing instructions.
35     """
36     if hasattr(pairing_codes, 'verification_uri_complete'):
37         # Generate QR code from the verification URI
38         qr_img = generate_qr_code(pairing_codes.verification_uri_complete)
39         
40         # Display the QR code on screen
41         # For GUI applications like Tkinter, PyQt, etc.
42         # display_image(qr_img)
43         
44         # For headless devices or testing, save to file
45         qr_img.save("frame_io_pairing_qr.png")
46         
47         print(f"Scan the QR code or visit: {pairing_codes.verification_uri}")
48         print(f"Manual code: {pairing_codes.user_code}")
49     else:
50         # Fallback for devices that received traditional pairing response
51         print(f"Enter code on Frame.io: {pairing_codes.user_code}")

Esempio JavaScript (web o Electron)

1 import QRCode from 'qrcode';
2 
3 /**
4  * Generate and display a QR code from the verification URI
5  * @param {string} verificationUriComplete - The complete verification URI from Frame.io
6  * @param {string} elementId - ID of the HTML element to display the QR code in
7  */
8 function displayQRCode(verificationUriComplete, elementId = 'qrcode-container') {
9   const element = document.getElementById(elementId);
10   
11   if (!element) {
12     console.error(`Element with ID ${elementId} not found`);
13     return;
14   }
15   
16   // Clear any existing content
17   element.innerHTML = '';
18   
19   // Generate QR code
20   QRCode.toCanvas(element, verificationUriComplete, { width: 250 }, function(error) {
21     if (error) {
22       console.error('Error generating QR code:', error);
23       // Fallback to displaying the URL as a link
24       element.innerHTML = `<a href="${verificationUriComplete}" target="_blank">Click here to pair</a>`;
25     }
26   });
27   
28   // Also display manual pairing information
29   const manualInfoDiv = document.createElement('div');
30   manualInfoDiv.innerHTML = `
31     <p>Scan the QR code or <a href="${verificationUriComplete}" target="_blank">click here</a> to pair your device.</p>
32     <p>Manual code: ${userCode}</p>
33   `;
34   element.parentNode.appendChild(manualInfoDiv);
35 }
36 
37 // Example usage in authorization flow
38 async function requestDeviceCode() {
39   try {
40     const response = await fetch('https://api.frame.io/v2/auth/device/code', {
41       method: 'POST',
42       headers: {
43         'x-client-version': '2.0.0',
44         'x-client-platypus-enabled': 'true'
45       },
46       body: new URLSearchParams({
47         'client_id': YOUR_CLIENT_ID,
48         'client_secret': YOUR_CLIENT_SECRET,
49         'scope': 'asset_create offline'
50       })
51     });
52     
53     const data = await response.json();
54     
55     if (data.verification_uri_complete) {
56       displayQRCode(data.verification_uri_complete);
57       window.userCode = data.user_code; // Store for display purposes
58     } else {
59       // Fallback for traditional pairing
60       displayManualPairingCode(data.user_code);
61     }
62     
63     // Begin polling for authorization
64     beginPollingForAuthorization(data.device_code, data.interval);
65     
66   } catch (error) {
67     console.error('Error requesting device code:', error);
68   }
69 }

Esempio Android (Java)

1 import android.graphics.Bitmap;
2 import android.widget.ImageView;
3 import com.google.zxing.BarcodeFormat;
4 import com.google.zxing.MultiFormatWriter;
5 import com.google.zxing.common.BitMatrix;
6 import com.journeyapps.barcodescanner.BarcodeEncoder;
7 
8 public void generateAndDisplayQRCode(String verificationUriComplete, ImageView qrCodeImageView) {
9     try {
10         MultiFormatWriter multiFormatWriter = new MultiFormatWriter();
11         BitMatrix bitMatrix = multiFormatWriter.encode(verificationUriComplete, 
12             BarcodeFormat.QR_CODE, 250, 250);
13         BarcodeEncoder barcodeEncoder = new BarcodeEncoder();
14         Bitmap bitmap = barcodeEncoder.createBitmap(bitMatrix);
15         
16         // Display in ImageView
17         qrCodeImageView.setImageBitmap(bitmap);
18         
19     } catch (Exception e) {
20         e.printStackTrace();
21         // Fallback to displaying the URL as text
22     }
23 }

Esempio iOS (Swift)

1 import UIKit
2 import CoreImage
3 
4 func generateQRCode(from string: String) -> UIImage? {
5     let data = string.data(using: String.Encoding.utf8)
6     
7     if let filter = CIFilter(name: "CIQRCodeGenerator") {
8         filter.setValue(data, forKey: "inputMessage")
9         filter.setValue("H", forKey: "inputCorrectionLevel")
10         
11         if let outputImage = filter.outputImage {
12             // Scale the image
13             let transform = CGAffineTransform(scaleX: 10, y: 10)
14             let scaledImage = outputImage.transformed(by: transform)
15             
16             // Convert to UIImage
17             let context = CIContext()
18             if let cgImage = context.createCGImage(scaledImage, from: scaledImage.extent) {
19                 return UIImage(cgImage: cgImage)
20             }
21         }
22     }
23     
24     return nil
25 }
26 
27 // Usage in your view controller
28 func displayPairingQRCode(verificationUriComplete: String) {
29     if let qrCodeImage = generateQRCode(from: verificationUriComplete) {
30         qrCodeImageView.image = qrCodeImage
31         
32         // Also show manual pairing information
33         pairingInstructionsLabel.text = "Scan the QR code or enter code manually"
34         pairingCodeLabel.text = userCode
35     } else {
36         // Fallback to manual code display
37         pairingInstructionsLabel.text = "Enter this code on Frame.io:"
38         pairingCodeLabel.text = userCode
39     }
40 }

Best practice per la visualizzazione del codice QR

Quando implementi l’associazione tramite codice QR, considera queste linee guida per offrire la migliore esperienza agli utenti:

Dimensioni ottimali: visualizza codici QR di almeno 200-250 px quadrati per una scansione affidabile.
Contrasto: assicurati che ci sia un contrasto elevato tra codice QR e sfondo (nero su bianco è l’ideale).
Correzione degli errori: usa livelli di correzione degli errori moderati (L o M) per bilanciare densità del codice e affidabilità.
Istruzioni chiare: fornisci indicazioni chiare su come eseguire la scansione del codice, ad esempio “Scansiona questo codice con la fotocamera dello smartphone per associare il dispositivo.”
Opzioni multiple: fornisci sempre il codice di associazione manuale insieme al codice QR come alternativa:

   Scan to pair:
   [QR CODE]
   
   Or enter code manually: 573131

Link ipertestuale per app mobili: se la tua integrazione è un’app mobile, includi verification_uri_complete come link toccabile, poiché gli utenti non possono scansionare un codice QR dallo stesso dispositivo.
Test: testa i codici QR con vari dispositivi e condizioni di illuminazione per garantire una scansione affidabile.

Esempio di visualizzazione del codice QR

Risoluzione dei problemi

Se riscontri problemi, consulta questi scenari e soluzioni comuni:

Pulsante “Collega dispositivo” non visibile: quando accedi al pannello di gestione C2C, questo potrebbe indicare:
Autorizzazioni insufficienti: se visualizzi un messaggio relativo alle autorizzazioni, contatta il tuo account manager per modificare le autorizzazioni o assegnare un ruolo appropriato. * Connessione al dispositivo esistente: dopo aver collegato un dispositivo, il pulsante principale “Aggiungi nuovo dispositivo” viene sostituito da un menu con tre puntini nell’angolo superiore destro del pannello Connessioni C2C.
Errore di client non valido: una risposta invalid_client indica una mancata corrispondenza delle informazioni del dispositivo, solitamente dovuta a un client_secret errato.
Errore di richiesta non valida: una risposta bad_request indica che il formato dei dati della richiesta è errato.Verifica i nomi dei campi e assicurati che tutti i campi obbligatori siano inclusi.

Se il problema non è trattato qui, condividi la tua esperienza per aiutarci a migliorare questa sezione di risoluzione dei problemi.

Passaggi successivi

Ti invitiamo a contattare il nostro team e a procedere alla guida sulla gestione delle autorizzazioni. Facci avere il tuo feedback!