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).
• OneSignal iOS SDK versão 5.2.15+ para rastreamento de cliques e Entrega Confirmada
• 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

​

2. Atualizar Info.plist

<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:

Encontre o nome do seu destino widget extension na lista de Targets do seu projeto. O nome do exemplo é OneSignalWidgetExtension.

Abra seu Podfile e adicione o seguinte código. Substitua OneSignalWidgetExtension pelo nome do seu destino widget extension.

Podfile

Full Podfile example

Copiar

Perguntar à IA

target 'OneSignalWidgetExtension' do
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
end

Feche o Xcode e execute pod repo update && pod install para instalar o pod OneSignalLiveActivities.Se você continuar vendo o erro “No such module ‘OneSignalLiveActivities’” depois disso, você pode adicionar a dependência manualmente indo para seu “Widget Extension Target” > General > Frameworks and Libraries > + icon. Selecione o framework OneSignalLiveActivities:

​

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

​

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

  Copiar

  Perguntar à IA

  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.

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

Você pode fazer um usuário ativar uma Live Activity enquanto interage com seu aplicativo.Por exemplo, quando um usuário tem um evento ativo acontecendo (eles fizeram um pedido, um jogo está em andamento, um evento está prestes a começar, etc.) e abre seu aplicativo, você pode exibir uma Live Activity automaticamente.Neste exemplo usaremos um botão para iniciar a Live Activity manualmente.

Copiar

Perguntar à IA

import SwiftUI
import ActivityKit
import OneSignalFramework
import OneSignalLiveActivities

struct ContentView: View {
  @StateObject private var viewModel = LiveActivityViewModel()

  var body: some View {
    VStack {
      Button("Start Live Activity") {
        viewModel.startLiveActivity()
      }
    }
  }
}

class LiveActivityViewModel: ObservableObject {

  func startLiveActivity() {
    let osAttributes = OneSignalLiveActivityAttributeData.create(activityId: "click-to-start")
    let attributes = OneSignalWidgetAttributes(name: "OneSignal", onesignal: osAttributes)
    let contentState = OneSignalWidgetAttributes.ContentState(emoji:"🤩", onesignal: nil)
    do {
        let activity = try Activity<OneSignalWidgetAttributes>.request(
            attributes: attributes,
            contentState: contentState,
            pushType: .token)
    } catch {
        print(error.localizedDescription)
    }
  }
}

Ao clicar no botão, ele lançará a Live Activity.

​

Rastreamento de cliques em Live Activity

​

Passo 1: Adicionar rastreamento de cliques ao seu widget

import OneSignalLiveActivities

struct ExampleAppFirstWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ExampleAppFirstWidgetAttributes.self) { context in
            VStack {
                Spacer()
                Text("Sample Text " + context.attributes.title).font(.headline)
                // Other UI code
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Pass nil if you don't need deep linking: .onesignalWidgetURL(nil, context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                // Other Dynamic Island regions
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T")
            } minimal: {
                Text("Min")
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Optional: Track Dynamic Island clicks separately
        }
    }
}

• Você pode passar uma URL para deep linking ou nil se quiser apenas rastreamento de cliques sem navegação
• A hierarquia de visualizações não pode incluir o modificador .widgetURL() da Apple se você estiver usando .onesignalWidgetURL()
• Aplique o modificador tanto à visualização principal da Live Activity quanto ao Dynamic Island se quiser rastrear cliques em ambos

​

Passo 2: Tratar URLs no seu app

import OneSignalLiveActivities

// AppDelegate example:
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    // Handle the original URL and navigate user
    if let url = originalURL {
        // Your custom URL routing logic
        return handleDeepLink(url)
    }
    return false
}

// SceneDelegate example:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
    guard let url = URLContexts.first?.url else { return }

    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

// SwiftUI example:
.onOpenURL { url in
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

​

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"
}'

​

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.

​

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

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?

• 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).

• 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.

​

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

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.