Configuração de desenvolvedor para Live Activities

​

Requisitos

• Siga a configuração do SDK iOS se estiver usando iOS nativo (Swift/Objective-C).
  • Se estiver usando um SDK wrapper (React Native, Flutter, Unity, etc.) siga a configuração do SDK Mobile e depois a Configuração do SDK de Live Activity multiplataforma.
• OneSignal iOS SDK versão 5.2.0+ para suporte a push-to-start (consulte as notas de lançamento).
• iOS 16.1+ e iPadOS 17+
• Use uma chave APNs .p8. A Apple não suporta certificados p12 com Live Activities.
• Xcode 14 ou superior

​

Configuração

​

1. Adicionar uma Widget Extension

Adicione um novo destino Widget Extension para seu aplicativo no Xcode.

Opções de Widget Extension para uma Live Activity.

Opções de Widget Extension para uma Live Activity.

​

2. Atualizar Info.plist

Adicione a chave Supports Live Activities ao Info e defina seu valor para Boolean YES

<key>NSSupportsLiveActivities</key>
<true/>

​

3. Adicionar SDK

• Package Manager
• Cocoapods

No seu destino Widget Extension, adicione o OneSignalFramework em General > Frameworks, Libraries and Embedded Content:

Adicione o OneSignalFramework ao seu destino Widget Extension

​

4. Definir atributos e UI do widget

• your-nameAttributes descreve o conteúdo estático da sua Live Activity.
• ContentState descreve o conteúdo dinâmico da sua Live Activity.

import ActivityKit
import WidgetKit
import SwiftUI
// Import the OneSignalLiveActivities module
// If you get an error about the module not being found, return to step 3 and ensure you have added the OneSignalLiveActivities pod correctly.
import OneSignalLiveActivities

// Update to inherit from OneSignalLiveActivityAttributes
// This will be used in your API requests to start a Live Activity
struct OneSignalWidgetAttributes: OneSignalLiveActivityAttributes  {
    // Update to inherit from OneSignalLiveActivityContentState
    public struct ContentState: OneSignalLiveActivityContentState {
        // Dynamic stateful properties about your activity go here!
        var emoji: String
        // Add a reference to OneSignalLiveActivityContentStateData?
        var onesignal: OneSignalLiveActivityContentStateData?
    }
    // Fixed non-changing properties about your activity go here!
    var name: String
    // Add a reference to OneSignalLiveActivityAttributeData
    var onesignal: OneSignalLiveActivityAttributeData
}

struct OneSignalWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
      // Update to use `for: the-name-of-your-attributes-struct`
      // This will be used in your API requests to start a Live Activity
        ActivityConfiguration(for: OneSignalWidgetAttributes.self) { context in
            // Lock screen/banner UI goes here
            // Update to show the attributes sent via the payload
            VStack {
                Text("Hello \(context.attributes.name) \(context.state.emoji)")
            }
            .activityBackgroundTint(Color.cyan)
            .activitySystemActionForegroundColor(Color.black)

        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded UI goes here.  Compose the expanded UI through
                // various regions, like leading/trailing/center/bottom
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text("Trailing")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text("Bottom \(context.state.emoji)")
                    // more content
                }
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T \(context.state.emoji)")
            } minimal: {
                Text(context.state.emoji)
            }
            .widgetURL(URL(string: "http://www.apple.com"))
            .keylineTint(Color.red)
        }
    }
}

​

5. Permitir associação ao destino principal

Permitir associação ao destino principal

​

6. Adicionar o método de configuração ao seu AppDelegate

// Import the OneSignalLiveActivities module
import OneSignalLiveActivities

// This should be added after initializing the OneSignal SDK
if #available(iOS 16.1, *) {
	OneSignal.LiveActivities.setup(OneSignalWidgetAttributes.self)
  // If you have multiple Live Activities, you can add them here with the setup method
  // OneSignal.LiveActivities.setup(LiveActivityWidgetAttributes-2.self)
}

​

Iniciar uma Live Activity

• Push-to-start
• Ativar no aplicativo

Envie uma requisição da API Push To Start. Certifique-se de que todos os nomes e IDs correspondam exatamente à configuração do seu widget (os parâmetros são sensíveis a maiúsculas e minúsculas). Se algo estiver faltando ou adicionado incorretamente, você pode encontrar problemas ao tentar lançar o widget.Aqui está um exemplo de requisição que funcionará para o exemplo acima.Substitua:

• YOUR_APP_ID pelo seu OneSignal App ID.
• YOUR_APP_API_KEY pela sua chave de API do OneSignal.
• OneSignalWidgetAttributes pelo nome da sua estrutura de Widget Attributes.
  curl

  Copy

  Ask AI

  curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/OneSignalWidgetAttributes' \
  --header 'Authorization: key YOUR_APP_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "event": "start",
      "activity_id": "push-to-start",
      "included_segments": [
          "Subscribed Users"
      ],
      "event_attributes": {
          "name": "World"
      },
      "event_updates": {
          "emoji":"🤩"
      },
      "name": "Live Activities Test",
      "contents": {
          "en": "A push started this Live Activity"
      },
      "headings": {
        "en": "Live Activity Started"
      }
    }'
  

Se você estiver seguindo o código de exemplo fornecido, você deve ver a Live Activity na tela de bloqueio do seu dispositivo.

Live Activity na tela de bloqueio

Você iniciou com sucesso uma Live Activity com push-to-start!Os usuários precisarão selecionar “Allow” para continuar recebendo atualizações.

​

Atualizar uma Live Activity

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/push-to-start/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "update",
    "event_updates": {
        "emoji": "😎"
    },
    "contents": {
        "en": "A push updated this Live Activity"
    },
    "name": "Live Activity Updated"
}'

Live Activity Atualizada

​

Encerrar uma Live Activity

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/my_activity_id/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "end",
    "event_updates": {
        "emoji": "👋"
    },
    "contents": {
        "en": "A push ended this Live Activity"
    },
    "name": "Live Activity Ended"
}'

• Use nosso método do SDK exit().
• Usuário desliza manualmente a Live Activity para removê-la.
• Usuário revoga permissão para Live Activities em suas Configurações do iOS.

Live Activity Encerrada

​

Melhores práticas e recomendações

​

Considerações de design

• Siga as Diretrizes de Interface Humana de Live Activities da Apple.
  • Priorize informações importantes para facilitar o entendimento em uma olhada rápida.
  • Não adicione elementos ao seu aplicativo que chamem atenção para a Dynamic Island.
  • Use margens e mantenha espaço entre elementos.
  • Use uma cor forte para o fundo. Projete para os modos Light e Dark.

​

Funcionalidade

• A Apple requer que cada apresentação de Live Activity seja suportada.
  • Compacta
  • Mínima
  • Expandida
  • Tela de Bloqueio
• Teste seus deep links.
• Revise o guia da Apple sobre Exibindo Dados Live com Live Activities.
• Evite exibir informações sensíveis em uma Live Activity.

​

Definir uma mensagem de fallback

• Em certos casos onde o usuário não consegue receber uma atualização para sua live activity, depois que uma foi iniciada, abrir o aplicativo deve atualizá-los para continuar
  • Para explicar isso, você definiria a data de obsolescência para uma data e hora no futuro, depois que você sabe que teria enviado sua primeira atualização para o usuário, e aqueles que não receberam a atualização veriam a mensagem de fallback.
  • Você pode escutar este estado “stale” em sua UI de widget para mostrar uma mensagem de fallback:
  swift

  Copy

  Ask AI

    struct ptsLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ptsAttributes.self) { context in
            //This will flip to true after the stale date
            let isStale = context.isStale 
            if !isStale{
                VStack {
                    Text("\(context.attributes.name) \(context.state.emoji)")
                        .activityBackgroundTint(Color.cyan)
                        .activitySystemActionForegroundColor(Color.black)
                }
            }  else {
            //If the message is stale, we request the user clicks the widget to open the app
                VStack {
                    Text("Something went wrong, please click to refresh")
                }
            }
    //... Rest of the widget UI
    }
  

---

## FAQ

### Qual é o orçamento para atualizações de alta prioridade?

A Apple não fornece um limite fixo para atualizações de alta prioridade (`priority: 10`), mas eles aplicam um orçamento dinâmico no nível do sistema. Enviar muitas atualizações de alta prioridade em um curto período pode resultar em limitação, onde atualizações são atrasadas ou descartadas.

Para reduzir o risco de limitação:
- Use uma mistura de níveis de prioridade: A Apple recomenda usar tanto `priority: 5` (padrão) quanto `priority: 10` (alta) para equilíbrio.
- Reserve `priority: 10` apenas para atualizações sensíveis ao tempo ou críticas (por exemplo, mudanças de status de pedido, placares de jogos).

Se seu caso de uso requer atualizações frequentes:
- Adicione a chave `NSSupportsLiveActivitiesFrequentUpdates` ao arquivo `Info.plist` do seu aplicativo, definida como Boolean `YES`.
- Quando este orçamento é excedido, o iOS pode solicitar ao usuário que permita atualizações adicionais. Se o usuário concordar, a Apple expandirá automaticamente o limite de atualização permitido para manter uma experiência sem problemas.

Para mais detalhes, consulte a [Documentação de Desenvolvedor da Apple](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).

### Posso ler atualizações de Live Activity do aplicativo principal?

Sim. Você pode observar atualizações para depuração ou sincronização de UI:

```swift
Task {
    for await content in activity.contentUpdates {
        print("LA activity id: \(activity.id), content update: \(content.state)")
    }
}
// Example output:
// LA activity id: EFE6D54D-F7E1-45EF-9514-4C2598F8DED2, content update: ContentState(message: "My message from payload")

Task {
    for await state in activity.activityStateUpdates {
        print("LA state update: \(state)")
        //Se você quiser fazer algo baseado no estado, você usaria isso:
      	if state != ActivityState.active {
            //Faça algo aqui
        }
    }
}

// Exemplo de saída 1 - LA encerrada, mas ainda visível
// LA state update: active

/* Estado pode ser igual a 4 valores possíveis no enum ActivityState
active, dismissed, ended, e stale
*/

​

A API retornou um 400 com uma mensagem de erro dizendo que estou acima do limite de assinantes. O que fazer?

​

Como evito enviar tanto push quanto Live Activities?

​

Solução de problemas

​

Sem destinatários

1. Verifique os parâmetros de caminho em sua requisição para garantir que você está enviando uma requisição formatada corretamente para o servidor. O App ID deve corresponder ao seu App ID usado no método OneSignal.Initialize e o tipo de atividade deve corresponder ao tipo que você definiu em seu arquivo de Live Activity.
2. No corpo da requisição da API Push To Start, você deve ter os seguintes parâmetros:

• event: "start"
• event_updates: Os dados dinâmicos que você definiu em sua estrutura sob o tipo de atividade e que são usados em seu widget. Garanta que o uso de maiúsculas/minúsculas e variáveis correspondam entre a requisição, o tipo e o widget.
• event_attributes: Dados estáticos seguem a mesma lógica que Event Updates e devem incluir todas as variáveis em uso, e devem corresponder em todas as partes da live activity e da requisição
• activity_id: Isso atribuirá um ID ao widget e é o que será usado para atualizar a atividade depois que ela for lançada no dispositivo do usuário.
• name: O Nome da Live Activity.
• contents: O conteúdo da mensagem necessário para enviar push.
• headings: O cabeçalho da mensagem necessário para enviar push.
• Um parâmetro de direcionamento como included_segments. Opções disponíveis.

​

Atividade enviada, mas não recebida

1. Garanta que a requisição está formatada corretamente. Se algum campo que é usado no Widget for omitido, a atividade pode não iniciar ou atualizar como esperado.
2. Em sua requisição da API, determine o nível de priority que você está definindo. Se você está definindo isso para 10 (prioridade mais alta), tente reduzir para 5 e teste novamente. A Apple limitará requisições sendo enviadas com muita frequência de acordo com seus próprios limites de taxa internos.