API de Esquemas de Live Activity

Um esquema de Live Activity é um JSON Schema para um tipo ActivityAttributes no seu aplicativo (por exemplo, FlightAttributes), cobrindo as duas metades do cartão: os campos de ContentState que mudam enquanto a atividade é executada, e os campos fixos durante toda a sua vida útil. Publique um esquema para que o elemento de Live Activity de uma jornada possa construir campos nomeados para ambas as metades a partir dele, em vez de um editor JSON bruto e uma lista livre de campos. O cartão e seu layout ainda são construídos no código do seu aplicativo. O esquema descreve apenas os dados que uma jornada preenche.

Esta API é para desenvolvedores que integram Live Activities. Consulte a API de Live Activities do iOS para iniciar e atualizar as próprias atividades.

Escrevendo um esquema

attributesType é o nome do tipo Swift que se conforma a ActivityAttributes em seu aplicativo. O Pushwoosh não lê seu código nem valida o nome em relação a ele — é apenas a string que a API armazena e a string que você passa para o campo attributes-type de startLiveActivity.

jsonSchema cobre as duas metades desse tipo, em dois lugares separados:

• Os campos de ContentState, os que mudam enquanto a atividade é executada, como o portão, o status ou a hora estimada de chegada de um voo, vão em properties na raiz do esquema.
• Os campos de ActivityAttributes, fixos durante toda a vida útil da atividade e definidos uma vez quando ela começa, como um número de voo, vão em uma seção attributes separada, com seu próprio properties e uma lista required opcional.

A seção attributes é opcional. Sem ela, os campos de ActivityAttributes continuam sendo uma lista livre de nome/valor de campo no elemento Live Activity, em vez de campos nomeados. Você ainda passa os valores reais dos atributos por live_activity.attributes em startLiveActivity — o esquema apenas declara seus nomes, tipos e quais são obrigatórios.

Exemplo

struct FlightAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable {
        var gate: String
        var status: String
        var estimatedTime: String
    }

    var flightNumber: String
}

flightNumber reside em ActivityAttributes. gate, status e estimatedTime residem em ContentState. Publique as duas metades como o esquema para attributesType: "FlightAttributes":

{
  "type": "object",
  "properties": {
    "gate": { "type": "string" },
    "status": { "type": "string" },
    "estimatedTime": { "type": "string" }
  },
  "attributes": {
    "properties": {
      "flightNumber": { "type": "string" }
    },
    "required": ["flightNumber"]
  }
}

required dentro de attributes torna flightNumber obrigatório na etapa Iniciar do elemento de Live Activity: deixá-lo em branco ali é rejeitado. O properties na raiz para os campos de ContentState não tem essa lista. Uma jornada nunca é obrigada a preencher gate, status ou estimatedTime.

Uma vez publicado, o elemento de Live Activity de uma jornada lê essa forma para oferecer campos nomeados para gate, status e estimatedTime em Conteúdo do card, em vez de um editor de estado de conteúdo bruto. O mesmo acontece para flightNumber em Atributos do card, em vez de uma lista livre de nome/valor de campo.

Veja Convenções abaixo para o formato e as regras de imutabilidade que se aplicam a jsonSchema, e Gerenciando esquemas no Control Panel no final desta página para as mesmas ações sem chamar a API diretamente.

URL Base

https://rpc-api.svc-nue.pushwoosh.com

Autenticação

Cada solicitação deve incluir um cabeçalho Authorization com seu token de API do Servidor:

Authorization: Api SEU_TOKEN_DE_API

Convenções

• A nomeação de campos é assimétrica. As solicitações aceitam tanto lowerCamelCase quanto o nome do proto. As respostas sempre retornam com os nomes dos campos do proto, em snake_case (attributes_type, json_schema) — os exemplos abaixo usam essa formatação.
• As versões são imutáveis. Uma versão publicada não pode ser editada — não há método Update. Publicar novamente com o mesmo attributesType e version falha com AlreadyExists. Uma mudança no widget é sempre uma nova versão. Omita version em Create para publicar a próxima versão livre para esse attributesType.
• Formato jsonSchema: deve ser um objeto JSON com "type": "object", com até 64 KB. null, um número, uma string simples ou um objeto sem "type": "object" são todos rejeitados, porque o formulário que o Pushwoosh constrói precisa de campos nomeados, que apenas um esquema de objeto possui. A seção opcional attributes, quando presente, deve ser ela própria um objeto com seu próprio properties e, opcionalmente, um array required que só nomeie campos declarados em attributes.properties. Um nome de campo não pode aparecer tanto em properties quanto em attributes.properties.

Endpoints

Método	Caminho	Descrição
GET	/api/live_activity_schemas	Listar os esquemas de um aplicativo
GET	/api/live_activity_schemas/{attributesType}/{version}	Obter uma versão de esquema
POST	/api/live_activity_schemas	Publicar uma nova versão de esquema
DELETE	/api/live_activity_schemas/{attributesType}/{version}	Excluir uma versão de esquema

Listar

Lista todos os attributesType para os quais um aplicativo publicou esquemas, com todas as suas versões, da mais nova para a mais antiga.

GET /api/live_activity_schemas

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo para listar os esquemas.
attributesType	string	Não	Restringir a lista a um tipo de ActivityAttributes.

Exemplo de resposta

{
  "schemas": [
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 2,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}",
      "created": "2026-09-01T10:00:00Z",
      "updated": "2026-09-01T10:00:00Z"
    },
    {
      "application": "XXXXX-XXXXX",
      "attributes_type": "FlightAttributes",
      "version": 1,
      "json_schema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
      "created": "2026-08-15T10:00:00Z",
      "updated": "2026-08-15T10:00:00Z"
    }
  ]
}

Obter

Retorna uma versão de esquema.

GET /api/live_activity_schemas/{attributesType}/{version}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
attributesType	string	Sim	Nome do tipo ActivityAttributes.
version	integer	Sim	Versão do esquema.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo ao qual o esquema pertence.

Resposta

Retorna { "schema": { ... } }, o objeto de esquema mostrado em Listar acima.

Criar

Publica uma nova versão de esquema para um attributesType. Retorna o esquema criado, incluindo a versão que lhe foi atribuída.

POST /api/live_activity_schemas

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo no qual publicar o esquema.
attributesType	string	Sim	Nome do tipo ActivityAttributes declarado em seu aplicativo.
jsonSchema	string	Sim	JSON Schema tanto de ContentState quanto de attributes. Veja Escrevendo um esquema acima.
version	integer	Não	Versão a ser publicada. Omita para obter a próxima versão livre para este attributesType.

Exemplo de solicitação

{
  "application": "XXXXX-XXXXX",
  "attributesType": "FlightAttributes",
  "jsonSchema": "{\"type\":\"object\",\"properties\":{\"gate\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}},\"attributes\":{\"properties\":{\"flightNumber\":{\"type\":\"string\"}},\"required\":[\"flightNumber\"]}}"
}

Resposta

Retorna { "schema": { ... } }, o objeto de esquema criado.

Cuidado

Publicar um par attributesType/version que já existe falha com AlreadyExists — as versões são imutáveis, então não há como sobrescrever uma. Publique sem version para obter a próxima.

Excluir

Exclui permanentemente uma versão do esquema.

DELETE /api/live_activity_schemas/{attributesType}/{version}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
attributesType	string	Sim	Nome do tipo ActivityAttributes.
version	integer	Sim	Versão do esquema a ser excluída.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
application	string	Sim	O código do aplicativo ao qual o esquema pertence.

Resposta

Retorna um objeto vazio em caso de sucesso.

Perigo

Isso não pode ser desfeito. O elemento de Live Activity de uma jornada construído com base na versão excluída mantém seus valores de conteúdo e atributos já salvos. Ele apenas perde as dicas de formulário para ambos a partir de então: o conteúdo volta a ser um editor JSON bruto, e os atributos voltam a ser uma lista livre de nome/valor de campo.

Respostas de erro

Status HTTP	Significado
400 Bad Request	Argumento inválido: um campo obrigatório está faltando, jsonSchema falha na regra de formato acima (incluindo uma seção attributes inválida), ou jsonSchema excede 64 KB.
401 Unauthorized	Cabeçalho Authorization ausente ou inválido.
403 Forbidden	O aplicativo não pertence à conta do chamador.
404 Not Found	O aplicativo, ou o par attributesType/version, não foi encontrado.
409 Conflict	Create foi chamado com um par attributesType/version que já existe (AlreadyExists na transmissão).
500 Internal Server Error	Falha inesperada no lado do servidor.

Gerenciando esquemas no Control Panel

O Control Panel oferece as mesmas ações da API sem a necessidade de chamá-la diretamente: listar versões por tipo, publicar uma nova versão, visualizar o JSON de uma versão e excluir uma versão (com uma confirmação, já que a exclusão é permanente). Consulte a configuração de esquemas de Live Activity do iOS para o caminho dos cliques.