Ações personalizadas

As Ações do Frame.io fornecem acesso rápido a operações de mídia comuns, como fazer download, renomear e duplicar itens, e também permitem que integrações com ferramentas e serviços de terceiros sejam exibidas diretamente na interface do usuário do Frame.io.

Sobre as Ações

Com a introdução das Ações personalizadas, os desenvolvedores podem configurar e gerenciar suas próprias Ações no Frame.io V4.Aproveitando o mesmo sistema de eventos subjacente dos Webhooks, as Ações personalizadas são um mecanismo alternativo para desenvolvedores conectarem seus ativos às ferramentas mais importantes para os usuários em sua Conta do Frame.io.

As Ações podem ser executadas por qualquer usuário que seja Membro do espaço de trabalho do Frame.io em que a Ação está ativada. Ao executar uma Ação, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor responde com um código de status HTTP para confirmar o recebimento ou com um callback personalizado para renderizar campos de formulário adicionais na IU do Frame.io. O aplicativo receptor pode ser um programa ou serviço hospedado por você, ou até mesmo uma ferramenta IPaaS low-code/no-code, como Workfront Fusion ou Zapier.

Use as Ações personalizadas para criar integrações diretamente no Frame.io como componentes de interface programáveis.Isso habilita fluxos de trabalho que podem ser acionados por usuários dentro do aplicativo, aproveitando o mesmo roteamento de eventos subjacente dos webhooks. Você pode criar formulários de uma ou várias etapas acionados pelo usuário que retornam ao Frame.io como outro formulário ou uma resposta básica. Quando um usuário clica em uma Ação personalizada em um Ativo, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor responde com um código de status HTTP para confirmar o recebimento ou responde com um callback personalizado que pode renderizar uma IU adicional no Frame.io.

Melhorias de Ações na V4

Aproveitando aprendizados obtidos com usuários da nossa versão Legacy, incluímos várias melhorias no conjunto de recursos de Ações no Frame.io V4:

Ações migradas

Há alguns pontos a considerar ao migrar para uma Conta Frame.io V4 que contém Ações personalizadas criadas anteriormente na versão legada do Frame.io.

Status da Ação

Após a migração da Conta para o Frame.io V4, todas as Ações personalizadas criadas em versões anteriores terão status “null” e serão desativadas automaticamente. Isso oferece aos usuários a oportunidade de primeiro atualizar suas Ações para usar a API V4 antes de ativá-las, pois qualquer Ação não atualizada falhará. Para identificar Ações nesse estado, acesse a página Configurações de Ações e consulte a coluna “Status” ou, se estiver usando a API, verifique o campo is_active.

Recursos acionáveis: arquivos, pastas e pilhas de versões

Considerando a separação dos tipos de ativo como recursos separados na API Frame.io V4, pode haver comportamentos a considerar ao interpretar o ID do recurso recebido no conteúdo da sua Ação. O comportamento para Arquivos individuais é direto, pois o ID refletirá o Arquivo específico no qual a Ação foi executada. Da mesma forma, para Pastas, você receberá o ID da Pasta na qual a Ação foi executada. No entanto, dependendo do seu caso de uso, você tem várias opções ao definir o comportamento da Ação. Use o ID da Pasta para fazer chamadas subsequentes à API do Frame.io se quiser interagir com o próprio recurso Pasta. Como alternativa, talvez você queira obter os filhos dessa Pasta para executar processamento adicional nos ativos contidos nela. Quando uma ação é Executada em uma Pilha de versões, o conteúdo conterá o ID do “Ativo principal”, que é o Arquivo mais acima na Pilha e o que é mostrado na IU do Frame.io.

Você pode ler mais sobre as diferenças entre a API Frame.io Legacy e a V4 no nosso Guia de migração.

Uma Ação personalizada requer:

Configurar sua Ação personalizada

Quando um usuário aciona uma Ação personalizada, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor pode responder com um código de status HTTP para confirmar o recebimento ou responder com um callback personalizado que renderiza IU adicional no Frame.io.

Configuração multiativo

O suporte a multiativo é orientado por configuração e deve ser ativado explicitamente no modal de configuração da Ação na Web. Isso pode ser feito durante a criação de uma nova Ação ou ao atualizar uma Ação existente. 

Quando o suporte a multiativo é ativado, o formato do conteúdo é alternado imediatamente. Os conteúdos legados e com suporte a multiativo são mutuamente exclusivos.

Conteúdo do Frame.io

Quando o usuário clica na sua Ação personalizada, um conteúdo é enviado para a URL definida no campo URL. Use esse conteúdo para identificar:

1
  POST /your/url
2
  {
3
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
5
    "data": {
6
        "description": "Pretty cool video.",
7
        "title": "Hey there!"
8
    },
9
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
10
    "project": {
11
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
    },
13
    "resources": [
14
        {
15
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
16
            "type": "file"
17
        },
18
        {
19
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
20
            "type": "file"
21
        }
22
    ],
23
    "type": "some.event",
24
    "user": {
25
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
26
    },
27
    "workspace": {
28
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
29
    }
30
  }

1
  POST /your/url
2
  {
3
      "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
      "action_id": "0e38b93a-9f10-4bc7-90bc-bd07a16e510a",
5
      "data": {
6
          "description": "Wow look at this.",
7
          "title": "Hey there!!"
8
      },
9
      "interaction_id": "dff6d369-7150-41f9-8e6f-4f0895f6b416",
10
      "project": {
11
          "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
      },
13
      "resource": {
14
          "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
15
          "type": "file"
16
      },
17
      "type": "some.event",
18
      "user": {
19
          "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
20
      },
21
      "workspace": {
22
          "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
23
      }
24
  }                                  

Migração a partir do Conteúdo legado

Interações, novas tentativas e tempos-limite

O interaction_id é um identificador exclusivo para rastrear a interação conforme ela evolui ao longo do tempo. Se não precisar responder ao usuário, retorne um código de status 200 e pronto. Embora seja opcional, recomendamos incluir informações sobre o resultado da ação, como uma mensagem de sucesso ou alerta de erro. Ações personalizadas oferecem suporte a callbacks de mensagem.

Criar um callback de mensagem

Na resposta HTTP ao evento de webhook, você pode retornar um objeto JSON descrevendo uma mensagem que será retornada ao usuário iniciador na IU do Frame.io.

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

As mensagens permitem fornecer feedback ao usuário diretamente na IU do Frame.io. Se precisar coletar informações adicionais do usuário, use 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, talvez esteja fazendo upload de conteúdo para um sistema que exige detalhes adicionais. Você pode descrever um Formulário na resposta, que o usuário preenche e envia de volta para você. Veja um exemplo:

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 envia o formulário, você receberá um evento na mesma URL do 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 adicionados a um 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 esses novos dados de formulário. Você pode responder com uma mensagem ou encadear outro formulário. Ao encadear Ações, Formulários e Mensagens, você pode programar fluxos de trabalho de várias etapas no Frame.io com lógica de negócios de um sistema externo.

Detalhes do formulário

Assim como mensagens, Formulários oferecem suporte aos atributos title e description que são renderizados na parte superior do formulário. Além disso, cada campo de formulário aceita os seguintes atributos de base:

Tipos de campo compatíveis

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
}

Lista de seleção

Define uma lista de opções da qual o usuário pode escolher. Deve incluir uma lista options, e cada membro da qual deve incluir um name legível e um value analisável por máquina.

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
}

Caixa de seleção

Uma caixa de seleção simples sem parâmetros adicionais.

1
{ 
2
   "type": "boolean", 
3
   "name": "enabled", 
4
   "label": "Enabled", 
5
   "value": "false"
6
}

Link

Um link simples sem parâmetros adicionais.

1
{
2
  "type": "link",
3
  "name": "videoLink",
4
  "label": "Video Link",
5
  "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc"
6
}

Modelo de permissões do Frame.io

Ações personalizadas têm um modelo de permissões especial: elas pertencem a um espaço de trabalho, não a qualquer usuário específico existente em uma Conta. Isso significa:

Segurança e verificação

Por padrão, todas as Ações personalizadas têm 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. A solicitação POST inclui o seguinte:

Verificação da assinatura

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

Feedback

Adoraríamos ouvir desenvolvedores e usuários finais sobre as formas como vocês gostariam de usar Ações no Frame.io V4. Entre em contato conosco com suas dúvidas, ideias e casos de uso para ajudar a orientar nossa priorização.