Visão geral das ações personalizadas

• JavaScript
• Python

As ações personalizadas são uma forma de criar integrações diretamente no Frame.io como componentes programáveis da interface do usuário.Isso possibilita toda uma classe de fluxos de trabalho que podem ser acionados pelos usuários dentro do aplicativo, aproveitando o mesmo roteamento de eventos subjacente dos Webhooks.Atualmente, as ações personalizadas estão disponíveis para Ativos e são exibidas no menu de contexto (clique com o botão direito do mouse) disponível em qualquer Ativo, conforme mostrado na imagem abaixo.

Um Ativo é uma representação robusta de um arquivo no S3 e de seu contexto no Frame.io.Isso inclui transcodificações, contexto de usuário/equipe/projeto e metadados.Quando um usuário clica em uma ação personalizada em um ativo, o Frame.io enviará um conteúdo de dados para um URL fornecido por você.O aplicativo destinatário pode, então, responder com um código de status HTTP para simplesmente confirmar o recebimento, ou pode responder com um callback personalizado capaz de renderizar uma interface de usuário adicional no Frame.io.

Configure sua ação personalizada

As ações personalizadas podem ser configuradas na área Ações personalizadas do developer.frame.io.Uma ação requer:

Clique — O que há no conteúdo que você recebe do Frame.io

Quando o usuário clicar na sua ação personalizada, um conteúdo será enviado para o URL que você especificou no 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
}

Você pode usar esse conteúdo para identificar:

• Qual das suas ações personalizadas foi clicada
• Qual recurso foi clicado
• Qual usuário realizou a ação

Criar um callback de mensagem

Em sua resposta HTTP ao evento do webhook, você pode retornar um objeto JSON descrevendo uma mensagem que será exibida ao Usuário que iniciou a ação na interface do Frame.io.Se quiser tentar criar uma mensagem e ver como ela ficará, experimente nosso Construtor de ações personalizadas, que permite configurar callbacks de mensagem ou formulários e ver como eles apareceriam no aplicativo web do Frame.io.

Aqui está um exemplo de objeto:

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

Isso exibirá um alerta para o usuário com a seguinte aparência:

As mensagens são uma maneira simples de fechar o ciclo de vida da ação, fornecendo contexto variável ao Usuário que está realizando a ação, sem que ele precise alternar de contexto.

Isso é suficiente para atender a muitos casos de uso, mas, às vezes, o conteúdo inicial e as chamadas subsequentes à API do Frame.io não fornecem contexto suficiente para o aplicativo receptor.Para esses cenários, também oferecemos suporte a Callbacks de formulário.

Criar um callback de formulário

Digamos que você precise de mais informações antes de iniciar seu processo.Por exemplo, você pode estar carregando conteúdo para um sistema que exige detalhes e configurações adicionais.Você pode “descrever” um Formulário em sua resposta, que o usuário realmente verá! E preencherá! E ele será enviado de volta para você!

Aqui está um exemplo de formulário que será exibido na interface do Frame.io para que o Usuário inicial possa preenchê-lo e enviá-lo:

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 o usuário enviar o formulário, você receberá um evento no mesmo URL da solicitação POST inicial:

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
}

Todos os campos personalizados que você adicionou ao seu formulário aparecem na seção data do conteúdo JSON enviado pelo Frame.io.Use o interaction_id para mapear a solicitação inicial e estes novos dados do formulário.E, novamente, se desejar, você pode responder com uma mensagem (ou até mesmo outro formulário!).

Ao encadear Ações, Formulários e Mensagens, você pode programar de forma eficaz fluxos de trabalho completos de ativos no Frame.io com a lógica de negócios de um sistema externo.

Use a imaginação! O céu é o limite.

Detalhes do formulário

Assim como as mensagens, os formulários suportam atributos title e description que são exibidos na parte superior do Formulário.Além disso, cada campo do formulário aceita os seguintes atributos básicos:

• type — Indica à interface do usuário do Frame.io qual tipo de dados esperar, bem como qual componente e renderização utilizar.
• label — Aparece na interface do usuário como o título acima do campo.
• name — Chave pela qual o campo será identificado no conteúdo subsequente.
• value — Valor com o qual o campo será preenchido previamente.

Tipos de campo suportados

Campo de texto

Um campo de texto simples, sem parâmetros adicionais.

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

Área de texto

Uma área de texto simples, sem parâmetros adicionais.

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
}

**Lista de seleção** Define uma lista de opções à qual o usuário pode escolher.Deve incluir uma lista deoptions, cada uma delas com um namelegível por humanos e umvalue` analisável por máquina.

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
}

Ações personalizadas e o modelo de permissões do Frame.io

Os Webhooks e as Ações personalizadas possuem um modelo especial de permissões: eles pertencem a uma Equipe, e não a nenhum usuário específico que faça parte de uma Equipe ou Conta.Isso significa que:

• Qualquer administrador ou gerente de equipe pode criar uma Ação personalizada em uma Equipe.
• Qualquer administrador ou gerente de equipe pode modificar ou excluir uma Ação personalizada existente em uma Equipe.Uma vez modificada, todos os usuários verão imediatamente o resultado da alteração.

Segurança

Por padrão, todas as Ações personalizadas possuem uma chave de assinatura gerada durante sua criação.Isso não é configurável.Essa chave pode ser usada para verificar se a solicitação se origina do Frame.io.

Verificação

Estão incluídos na solicitação POST os seguintes elementos

Verificação da assinatura

1. Extrai a assinatura dos cabeçalhos HTTP
2. Cria uma mensagem para assinar combinando a versão, o tempo de entrega e o corpo da solicitação

• v0:timestamp:body

3. Computa a assinatura HMAC SHA-256 utilizando seu segredo de assinatura.

• Observação: a assinatura fornecida é precedida por v0=.Atualmente, o Frame.io possui apenas essa versão para assinar solicitações.Você precisará adicionar esse prefixo à sua assinatura computada.

4. Compare!

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