Guía práctica: Autorizar | Frame.io API Documentation

Introducción

En esta guía se explica el proceso de autenticación y autorización para dispositivos Camera to Cloud (C2C) en un proyecto de Frame.io. Exploraremos tanto el método estándar de entrada manual de código como el enfoque mejorado de emparejamiento con código QR para ofrecer una experiencia de usuario óptima.

¿Qué necesitaré?

Revise la guía Antes de empezar la implementación si aún no lo ha hecho. Debería haber recibido un client_secret de nuestro equipo para identificar su integración. Si no es así, consulte esta introducción al ecosistema de C2C y póngase en contacto con nuestro equipo.

Requisitos previos para el emparejamiento con código URL y QR

Para implementar el emparejamiento con código URL y QR, asegúrese de cumplir estos requisitos:

Compatibilidad del dispositivo: Verifique que su dispositivo sea compatible con la generación de código URL/QR durante el proceso de emparejamiento.

Descripción detallada del flujo de autorización

Para entender el flujo de autorización desde la perspectiva del usuario, consulte estos recursos:

Artículo de asistencia para añadir dispositivos nuevos.
Vídeo de formación sobre la autorización de un dispositivo Teradek Cube.

Este proceso de autorización minimiza los requisitos de implementación. No necesitará:

Redirigir a exploradores web (a menos que use el emparejamiento con código URL)
Gestionar la autenticación de usuarios de Frame.io
Presentar interfaces de selección de cuenta/proyecto
Desarrollar componentes complejos de la IU más allá de las pantallas básicas de información

Mejora de la experiencia del usuario mediante el emparejamiento con código URL

Los usuarios modernos esperan interacciones eficientes con los dispositivos. Aunque el proceso actual de emparejamiento manual funciona adecuadamente, se puede optimizar.

Al implementar el emparejamiento con código URL y QR, similar al que se usa en los servicios de streaming como Netflix o Disney+, podemos optimizar significativamente el proceso, minimizar los errores en la entrada de código y reducir el tiempo que dura el emparejamiento.

Identificación del dispositivo (client_id)

Cada dispositivo físico requiere un identificador único para hacer el seguimiento de las conexiones dentro del proyecto de un usuario.

Para los dispositivos, este identificador es el client_id, que es esencial durante la autorización. Al realizar la implementación, puede utilizar las fuentes de identificador apropiadas, como los números de serie del dispositivo, los UUID u otras cadenas únicas. Si está realizando la integración en un dispositivo Apple, recomendamos usar un UUID persistente único que sea coherente durante los reinicios del dispositivo. Tenga cuidado con la información de identificación personal. Las direcciones de correo electrónico del usuario no son valores apropiados de client_id.

Además, asegúrese de que controla el identificador. Las direcciones MAC del dispositivo no son adecuadas ya que no son propiedad de su software y pueden constituir información de identificación personal.

Si necesita orientación para seleccionar un identificador apropiado, nuestro equipo puede ayudarle a determinar un valor adecuado que simplifique la integración.

Paso 1: Solicitar un código de dispositivo

Para comenzar la implementación, solicite un código de dispositivo a través del punto final /v2/auth/device/code:

Método de emparejamiento tradicional

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

Habilitación del emparejamiento con código URL

Para el emparejamiento con código URL, modifique la llamada API con encabezados adicionales:

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: Estos puntos finales de autenticación aceptan exclusivamente datos de formulario, no JSON. Después de la autenticación, otros puntos finales aceptarán cargas útiles JSON, pero los puntos finales de autenticación rechazarán las solicitudes JSON.

Parámetros de carga útil

client_id: El identificador único de su dispositivo físico. Debe garantizarse que sea único, como un número de serie o un UUID.
client_secret: Lo proporciona el servicio de asistencia de Frame.io para identificar su modelo de dispositivo. Este valor confidencial debe mantenerse protegido de los usuarios y cifrado cuando se almacene.
scope: Los permisos solicitados, separados por espacios. Los dispositivos pueden solicitar:

* asset_create: Permite la creación y la carga de activos. * offline: Permite la actualización de autorización mediante token de actualización. Sin este ámbito, los usuarios tendrían que volver a autorizar su dispositivo cada 8 horas, ya que los tokens de autorización caducan.

En implementaciones prácticas, los dispositivos normalmente solicitan ambos ámbitos.

Comprensión de la respuesta de la API

La solicitud genera una respuesta similar a la siguiente:

Respuesta de emparejamiento tradicional

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

Respuesta de emparejamiento con 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"
}

Desglose de la respuesta

device_code: Este identificador interno debe permanecer oculto e identifica la solicitud de autorización durante el sondeo.
expires_in: El periodo de validez del código en segundos.
interval: El intervalo de sondeo recomendado en segundos.
name: El identificador del dispositivo de conexión.
user_code: El código de seis dígitos para la entrada manual en Frame.io y realizar el emparejamiento del dispositivo.
verification_uri: La URL base para la entrada manual si el escaneo del código QR no está disponible.
verification_uri_complete: La URL completa que contiene el código de emparejamiento y destinada al hipervínculo dentro de una aplicación móvil o generación de código QR para optimizar la navegación del usuario a la interfaz de emparejamiento.

Cómo mostrar el código QR al usuario

Con el verification_uri_complete, genere y muestre un código QR en la pantalla del dispositivo para que el usuario lo escanee, de manera que se facilite un emparejamiento eficiente.

Ejemplo: Pantalla del dispositivo en la que se muestra un código QR

Ejemplo de pantalla de emparejamiento con código QR en el dispositivo Proporcione siempre opciones de reserva: Muestre el user_code y el verification_uri para facilitar la entrada manual cuando el escaneo del código QR no sea posible. También puede mostrar el verification_uri como un código QR estático para el escaneo móvil. Para integraciones de aplicaciones móviles, incluya el verification_uri_complete como un hipervínculo en el que se puede pulsar, ya que los usuarios no pueden escanear códigos QR desde el dispositivo que ejecuta la aplicación.

Paso 2: Sondear para obtener la autorización del usuario

Después de proporcionar el código de emparejamiento o código URL, verifique la entrada del usuario con esta solicitud:

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

Parámetros de carga útil

client_id: El mismo identificador que se ha utilizado en el paso 1.
device_code: El valor de device_code devuelto anteriormente.
grant_type: El identificador del tipo de concesión OAuth, siempre urn:ietf:params:oauth:grant-type:device_code para esta implementación.

Los intentos iniciales de sondeo normalmente devuelven:

{
  "error": "authorization_pending"
}

Este error no grave indica que el usuario no ha completado la entrada de código. Siga con el sondeo hasta que termine.

Nota para dispositivos de la aplicación para iOS: Si el usuario cambia a la aplicación para iOS de Frame.io para introducir el código de emparejamiento, puede que su aplicación pase al segundo plano. Cuando su aplicación vuelva a estar activa, como en applicationDidBecomeActive, reanude el sondeo para que el flujo de autorización pueda continuar sin requerir que el usuario reinicie el emparejamiento.

Si recibe:

{
  "error": "expired_token"
}

El código caducó antes de la entrada del usuario. Genere un código/código QR nuevo a través del paso 1, preséntelo al usuario y reanude el sondeo.

Una autorización correcta produce:

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

Enhorabuena por autorizar correctamente su dispositivo Camera to Cloud.

Examinemos esta respuesta:

access_token: Su credencial de autenticación para el acceso al backend de Frame.io, necesaria en los encabezados para futuras solicitudes de API.
expires_in: El periodo de validez del token de acceso en segundos; después de este periodo, es necesario actualizarlo.
refresh_token: Se usa para la administración del token de acceso, principalmente para actualizar la autorización, pero también aplicable para la revocación.
token_type: Siempre será bearer para implementaciones de API de C2C, sin que sea necesario realizar ninguna acción.

Unión de todos los pasos

Ahora vamos a implementar estas llamadas API en pseudocódigo similar a Python y gestionaremos la posible caducidad del código del 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: El bucle externo gestiona casos donde los códigos de emparejamiento caducan y se requieren códigos nuevos.

Como paso final, recupere y muestre información del proyecto desde Frame.io para confirmar el emparejamiento correcto al proyecto previsto. Veremos esto en el próximo tutorial.

Cómo crear y mostrar códigos QR para el emparejamiento

Al implementar el emparejamiento con código URL/QR, necesitará generar un código QR a partir del valor del verification_uri_complete en la respuesta. A continuación, se muestran algunos ejemplos que utilizan bibliotecas populares en diferentes lenguajes de programación:

Ejemplo de 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}")

Ejemplo de 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 }

Ejemplo de 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 }

Ejemplo de 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 }

Prácticas recomendadas para mostrar códigos QR

Al implementar el emparejamiento con código QR, tenga en cuenta estas directrices para obtener la mejor experiencia del usuario:

Tamaño óptimo: Muestre códigos QR de al menos 200-250 píxeles cuadrados para un escaneo fiable.
Contraste: Asegúrese de que haya un alto contraste entre el código QR y el fondo (negro sobre blanco es lo ideal).
Corrección de errores: Use niveles de corrección de errores moderados (L o M) para equilibrar la densidad y la fiabilidad del código.
Instrucciones claras: Proporcione una orientación clara sobre cómo escanear el código, como “Escanee este código con la cámara de su smartphone para emparejar su dispositivo.”
Varias opciones: Proporcione siempre el código de emparejamiento manual junto con el código QR como opción de reserva:

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

Hipervínculo para aplicaciones móviles: Si su integración es una aplicación móvil, incluya el verification_uri_complete como un vínculo en el que se puede pulsar, ya que los usuarios no pueden escanear un código QR desde el mismo dispositivo.
Pruebas: Pruebe sus códigos QR con varios dispositivos y condiciones de iluminación para garantizar un escaneo fiable.

Ejemplo de cómo se muestra un código QR

Solución de problemas

Si surgen problemas, consulte estos escenarios comunes y sus soluciones:

Botón “Dispositivo conectado” no visible: Al acceder al panel de administración de C2C, esto podría indicar:

* Permisos insuficientes: Si ve un mensaje sobre permisos, póngase en contacto con su administrador de cuentas para ajustar los permisos o asignar una función apropiada. * Conexión de dispositivo existente: Después de conectar un dispositivo, el botón principal “Añadir dispositivo nuevo” se reemplaza por un menú de tres puntos situado en la esquina superior derecha del panel Conexiones de C2C.

Error de cliente no válido: Una respuesta invalid_client indica una discrepancia en la información del dispositivo, generalmente debido a un client_secret incorrecto.
Error de solicitud incorrecta: Una respuesta bad_request indica que los datos de la solicitud tienen un formato incorrecto. Verifique los nombres de los campos y asegúrese de que todos los campos obligatorios estén incluidos.

Si su problema no aparece aquí, comparta su experiencia para que podamos mejorar esta sección de solución de problemas.

Próximos pasos

Le recomendamos que se ponga en contacto con nuestro equipo y que luego continúe con la guía Administración de autorizaciones. Quedamos a la espera de recibir sus comentarios.