Panoramica delle azioni personalizzate

• JavaScript
• Python

Le azioni personalizzate consentono di creare integrazioni direttamente in Frame.io come componenti programmabili dell’interfaccia utente.In questo modo viene abilitata un’intera classe di flussi di lavoro che possono essere attivati dagli utenti all’interno dell’app, sfruttando lo stesso indirizzamento di eventi sottostante dei webhook.Attualmente, le azioni personalizzate sono disponibili per le risorse e vengono visualizzate nel menu a discesa contestuale disponibile su qualsiasi risorsa, come mostrato nell’immagine seguente.

Una risorsa è una rappresentazione completa di un file in S3 e del suo contesto in Frame.io.Include transcodifiche, contesto di utente/team/progetto e metadati.Quando un utente fa clic su un’azione personalizzata in una risorsa, Frame.io invia un payload a un URL che fornisci. L’applicazione ricevente può quindi rispondere con un codice di stato HTTP per riconoscere semplicemente la ricezione oppure può rispondere con un callback personalizzato che permette di mostrare un’interfaccia utente aggiuntiva in Frame.io.

Configura un’azione personalizzata

Le azioni personalizzate possono essere configurate nell’area Azioni personalizzate di developer.frame.io. Un’azione richiede:

Clic - Cosa contiene il payload ricevuto da Frame.io

Quando l’utente fa clic sull’azione personalizzata, un payload verrà inviato all’URL specificato nel campo URL.

1
POST /your/url
2
{
3
  "action_id": "2444cccc-7777-4a11-8ddd-05aa45bb956b",
4
  "interaction_id": "aafa3qq2-c1f6-4111-92b2-4aa64277c33f",
5
  "project": {
6
    "id": "a7d6a74b-d45d-4019-9069-24651e0b9f64"
7
  },
8
  "resource": {
9
    "id": "9q2e5555-3a22-44dd-888a-abbb72c3333b",
10
    "type": "asset"
11
  },
12
  "team": {
13
    "id": "54353cd2-c6ee-4aa1-954a-ce9e19602aa9"
14
  },
15
  "type": "my.action",
16
  "user": {
17
    "id": "fb57eee0-79f2-4bc7-9b70-99fbc175175c"
18
  }
19
}

Puoi utilizzare questo payload per identificare:

• Su quale delle tue azioni personalizzate è stato fatto clic
• Su quale risorsa è stato fatto clic
• Quale utente ha eseguito l’azione

Crea un callback del messaggio

Nella risposta HTTP all’evento webhook, puoi restituire un oggetto JSON che descrive un messaggio che verrà restituito all’utente che ha avviato l’azione nell’interfaccia utente di Frame.io. Se vuoi provare a creare un messaggio e vedere come sarà, puoi provare il nostro strumento di creazione di azioni personalizzate, che permette di impostare callback di messaggi o moduli e vedere come apparirebbero nella web app di Frame.io.

Ecco un oggetto di esempio:

1
{
2
  "title": "Success!",
3
  "description": "The thing worked! Nice."
4
}

Questo mostrerà all’utente un avviso di questo tipo:

I messaggi sono un modo semplice per chiudere il ciclo di vita dell’azione in modo da fornire un contesto variabile all’utente attivo, senza chiedergli di cambiare contesto.

Ciò è sufficiente per molti casi d’uso, ma a volte il payload iniziale e le successive chiamate all’API di Frame.io non forniranno un contesto sufficiente per l’applicazione ricevente. In questi scenari, supportiamo anche i callback dei moduli.

Crea un callback del modulo

Supponiamo che tu abbia bisogno di maggiori informazioni prima di iniziare il processo. Ad esempio, potresti caricare dei contenuti in un sistema che richiede dettagli e impostazioni aggiuntive. Nella risposta puoi “descrivere” un modulo che l’utente vedrà effettivamente. Potrà compilarlo e ti verrà rispedito subito!

Ecco un esempio che mostra un modulo nell’interfaccia utente di Frame.io che l’utente iniziale può compilare e inviare:

1
{
2
  "title": "Need some more info!",
3
  "description": "Getting ready to submit this file!",
4
  "fields": [
5
    {
6
      "type": "text",
7
      "label": "Title",
8
      "name": "title",
9
      "value": "MyVideo.mp4"
10
    },
11
    {
12
      "type": "select",
13
      "label": "Captions",
14
      "name": "captions",
15
      "options": [
16
        {
17
          "name": "Off",
18
          "value": "off"
19
        },
20
        {
21
          "name": "On",
22
          "value": "on"
23
        }
24
      ]
25
    }
26
  ]
27
}

Quando l’utente invia il modulo, riceverai un evento sullo stesso URL del POST iniziale:

1
POST /your/url​
2
{
3
  "type": "your-specified-event-name",
4
  "interaction_id": "the-same-id-as-before",
5
  "action_id": "unique-id-for-this-custom-action",
6
  "data":{
7
    "title": "MyVideo.mp4",
8
    "captions": "off"
9
  }
10
}

Tutti i campi personalizzati aggiunti al modulo appaiono nella sezione data del payload JSON inviato da Frame.io. Usa interaction_id per mappare la richiesta iniziale e questi nuovi dati del modulo. Se vuoi, puoi rispondere con un messaggio o anche con un altro modulo!

Concatenando azioni, moduli e messaggi, puoi programmare in modo efficace interi flussi di lavoro delle risorse in Frame.io con logica di business da un sistema esterno.

Fai volare l’immaginazione! Non ci sono limiti.

Dettagli del modulo

Come per i messaggi, i moduli supportano gli attributi title e description che vengono visualizzati nella parte superiore del modulo. Oltre a questo, ogni campo del modulo accetta i seguenti attributi di base:

• Type:: indica all’interfaccia utente di Frame.io che tipo di dati aspettarsi e quale componente e rendering.
• label: appare nell’interfaccia utente come intestazione sopra il campo.
• name: chiave con cui il campo verrà identificato nel payload successivo.
• value: valore con cui precompilare il campo.

Tipi di campi supportati

Campo di testo

Un semplice campo di testo senza parametri aggiuntivi.

1
{  
2
  "type": "text",
3
  "label": "Title",
4
  "name": "title",
5
  "value": "MyVideo.mp4"
6
}

Area di testo

Una semplice area di testo senza parametri aggiuntivi.

1
{  
2
  "type": "textarea",
3
  "label": "Description",
4
  "name": "description",
5
  "value": "This video is really, really popular."
6
}

Select list Defines a picklist that the user can choose from. Must include an options list, each member of which should include a human-readable name, and a machine-parseable value.

1
{
2
  "type": "select",
3
  "label": "Captions",
4
  "name": "captions",
5
  "value": "off",
6
  "options": [
7
       {
8
         "name": "Off",
9
         "value": "off"
10
       },
11
       {
12
         "name": "On",
13
         "value": "on"
14
      }
15
   ]
16
}

**Elenco di selezione** Definisce un elenco di selezione dal quale l'utente può scegliere. Deve includere un elenco di opzioni (options), ognuna delle quali deve includere un nome (name) leggibile dall'uomo e un valore (value`) analizzabile dalla macchina.

1
{
2
3
4
  
5
6
"type": "select",
7
8
9
  
10
11
"label": "Captions",
12
13
14
  
15
16
"name": "captions",
17
18
19
  
20
21
"value": "off",
22
23
24
  
25
26
"options": [
27
28
29
       
30
31
{
32
33
34
         
35
36
"name": "Off",
37
38
39
         
40
41
"value": "off"
42
43
44
       
45
46
},
47
48
49
       
50
51
{
52
53
54
         
55
56
"name": "On",
57
58
59
         
60
61
"value": "on"
62
63
64
      
65
66
}
67
68
69
   
70
71
]
72
73
74
75
76
}

Azioni personalizzate e modello di autorizzazioni di Frame.io

I webhook e le azioni personalizzate seguono un modello di autorizzazioni speciale: appartengono a un team, non a un utente specifico che fa parte di un team o di un account. Ciò significa che:

• Un amministratore o un team manager può creare un’azione personalizzata in un team.
• Un amministratore o un team manager può modificare o eliminare un’azione personalizzata che esiste in un team. Una volta apportata la modifica, tutti gli utenti potranno vederne immediatamente il risultato.

Sicurezza

Per impostazione predefinita, per tutte le azioni personalizzate viene generata una chiave di firma durante la creazione. Non è configurabile.Questa chiave può essere utilizzata per verificare che la richiesta provenga da Frame.io.

Verifica

Nella richiesta POST sono inclusi i seguenti elementi

Verifica della firma

1. Estrai la firma dalle intestazioni HTTP
2. Crea un messaggio da firmare combinando la versione, l’ora di consegna e il corpo della richiesta

• v0:timestamp:body

3. Calcola la firma HMAC SHA256 utilizzando il secret di firma.

• Nota: la firma fornita ha il prefisso v0=. Al momento Frame.io ha solo questa versione per firmare le richieste.Dovrai aggiungere questo prefisso alla firma calcolata.

4. Confronta!

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify webhook/custom action signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the frame.io API for the given request
11
        body (str): Custom Action body from the received POST
12
        secret (str): The secret for this Custom Action that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False