Guia de integração básica do SDK do Unity

Este guia orienta você na integração do SDK do Pushwoosh para Unity em seu aplicativo.

Pré-requisitos

Requisitos

• Uma conta Pushwoosh.
• Um projeto Pushwoosh configurado em sua conta.
• Unity 2021.3 ou posterior.
• Para iOS:
  • Uma plataforma iOS configurada para enviar notificações push. Recomendamos o uso da Autenticação Baseada em Token como a abordagem mais simples.
  • Defina o Gateway como Sandbox para enviar pushes para um simulador.
  • Para obter o SDK nativo do iOS com o Swift Package Manager: Unity 2021.3.15 ou posterior, Target minimum iOS Version definida como 15.0 ou posterior e acesso ao github.com quando o Xcode compila o projeto. Com o Unity 2021.3.0–2021.3.14 ou um destino de iOS inferior, o SDK é adicionado com o CocoaPods (consulte Escolha como o SDK do iOS é adicionado).
• Para Android:
  • Uma plataforma Android configurada.
  • O número do projeto (também conhecido como Sender ID), o arquivo google-services.json e o nome do pacote do seu projeto Firebase.
  • Um projeto Firebase conectado ao seu aplicativo Android. Siga o guia de configuração do Firebase se necessário.
• Seu Código de Aplicativo Pushwoosh e Token de API de Dispositivo Pushwoosh do Painel de Controle Pushwoosh.

Passos de integração

1. Adicionar o SDK do Pushwoosh para Unity

UPM via Scoped Registry (recomendado)

Adicione o seguinte ao seu Packages/manifest.json:

Packages/manifest.json

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

Adicione apenas os pacotes de plataforma que você precisa. Por exemplo, omita com.pushwoosh.unity.android se você visa apenas o iOS.

UPM via Git URL

No Unity, vá para Window > Package Manager > + > Add package from git URL e adicione as seguintes URLs uma por uma:

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

.unitypackage

Baixe o Pushwoosh.unitypackage dos Lançamentos do GitHub e importe via Assets > Import Package > Custom Package.

2. Instalar o External Dependency Manager

A parte Android do SDK requer o External Dependency Manager for Unity (EDM4U) para resolver as dependências nativas do Android. Pule esta etapa se você desenvolve apenas para iOS.

Adicione o seguinte registro com escopo ao seu Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

Em seguida, adicione o pacote às suas dependências:

"com.google.external-dependency-manager": "1.2.183"

3. Escolha como o SDK do iOS é adicionado

Por padrão, a exportação para iOS obtém o SDK nativo do pacote Swift Pushwoosh-XCFramework com o Swift Package Manager. Você não precisa do CocoaPods nem do EDM4U para iOS e não executa pod install.

Para alterar a origem do SDK do iOS ou adicionar módulos opcionais, abra Window > Pushwoosh SDK Setup no Unity Editor:

• Em iOS SDK from, selecione Swift Package Manager ou CocoaPods.
• Com o Swift Package Manager, em Modules (Swift Package Manager only), selecione os módulos opcionais que seu aplicativo usa: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. Os módulos são vinculados ao target do aplicativo. Para usar um módulo na sua própria extensão de aplicativo, adicione-o ao target da extensão no Xcode. Com o CocoaPods, a exportação é feita sem esses módulos.

A exportação volta para o CocoaPods, e o console do Unity informa o motivo, quando qualquer uma destas condições se aplica:

• CocoaPods está selecionado em Window > Pushwoosh SDK Setup.
• O projeto já tem um pod PushwooshXCFramework, em um arquivo *Dependencies.xml lido pelo EDM4U ou no Podfile. Para mudar para o Swift Package Manager, remova o pod. Para Geozones, remova o pod PushwooshXCFramework/Geozones e selecione PushwooshGeozones em Window > Pushwoosh SDK Setup.
• A versão do Unity é anterior à 2021.3.15.
• Target minimum iOS Version é inferior a 15.0.

Com o CocoaPods, o EDM4U não é necessário. O SDK executa pod install após a exportação e gera o Podfile por conta própria, a menos que o EDM4U esteja instalado e grave o Podfile em seu lugar. Se pod install falhar, o console do Unity mostra o erro. Execute pod install na pasta do projeto Xcode exportado.

Se o seu ambiente de build não consegue acessar o github.com, o Xcode não consegue resolver o pacote Swift. Selecione CocoaPods em Window > Pushwoosh SDK Setup para esses builds.

A exportação com o Swift Package Manager mantém o Unity-iPhone.xcworkspace, portanto scripts de build e CI que compilam o workspace funcionam sem alterações.

Atualização a partir de uma configuração com CocoaPods

Ao atualizar para a versão 6.3.0 ou posterior, um projeto que obtinha o SDK do iOS pelo CocoaPods ou pelo EDM4U passa a usar o Swift Package Manager, a menos que uma das condições acima o mantenha no CocoaPods.

• Para manter o CocoaPods, selecione-o em Window > Pushwoosh SDK Setup.
• Se você exportar com o Swift Package Manager para a pasta de uma exportação anterior com CocoaPods, o pod do Pushwoosh é removido do Podfile, mas o projeto Xcode ainda faz referência a Pods e só é compilado a partir do Unity-iPhone.xcworkspace. Compile o workspace ou exporte para uma nova pasta para obter um projeto sem CocoaPods.

4. Inicializar o SDK

Crie um script PushNotificator.cs e anexe-o a qualquer GameObject na cena:

PushNotificator.cs

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

Substitua:

• XXXXX-XXXXX pelo seu Código de Aplicativo Pushwoosh.
• XXXXXXXXXXXX pelo número do seu projeto Firebase (apenas Android).

5. Configuração nativa do iOS

5.1 Capabilities

Após construir o projeto iOS a partir do Unity, abra o projeto Xcode gerado e adicione as seguintes capabilities em Signing & Capabilities:

• Push Notifications
• Background Modes com Remote notifications marcado

Para Time Sensitive Notifications (iOS 15+), adicione também a capability Time Sensitive Notifications.

5.2 Info.plist

Adicione o Token de API de Dispositivo Pushwoosh ao seu Info.plist:

Info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

5.3 Rastreamento de entrega de mensagens

Adicione um alvo de Notification Service Extension ao seu projeto Xcode. Isso é necessário para o rastreamento preciso da entrega e Rich Media no iOS.

Siga o guia nativo para adicionar o alvo da extensão.

6. Configuração nativa do Android

6.1 Adicionar arquivo de configuração do Firebase

Coloque o arquivo google-services.json no diretório Assets do seu projeto Unity.

6.2 Adicionar metadados do Pushwoosh

Adicione o Token de API de Dispositivo Pushwoosh ao seu Assets/Plugins/Android/AndroidManifest.xml dentro da tag <application>:

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

Cuidado

Certifique-se de dar ao token acesso ao aplicativo correto em seu Painel de Controle Pushwoosh. Saiba mais

7. Executar o projeto

1. Compile e execute o projeto na sua plataforma de destino.
2. Conceda permissão para notificações push quando solicitado.
3. Vá para o Painel de Controle Pushwoosh e envie uma notificação push.

Integração estendida

Nesta fase, você pode enviar e receber notificações push. As seções abaixo cobrem a funcionalidade principal do SDK.

Listeners de eventos de notificação push

O SDK fornece dois listeners de eventos para lidar com notificações push:

• OnPushNotificationsReceived — acionado quando uma notificação push chega
• OnPushNotificationsOpened — acionado quando um usuário toca em uma notificação

Configure esses listeners durante a inicialização do SDK:

PushNotificator.cs

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

Configuração do usuário

Personalize as notificações push identificando usuários e definindo suas propriedades:

// Define o ID do usuário para rastreamento entre dispositivos
Pushwoosh.Instance.SetUserId("user-123");

// Define o e-mail do usuário
Pushwoosh.Instance.SetEmail("user@example.com");

// Define o usuário com ID e e-mail
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Define o idioma preferido
Pushwoosh.Instance.SetLanguage("en");

Tags

Tags são pares de chave-valor atribuídos a dispositivos, permitindo a segmentação de usuários e o envio de mensagens direcionadas:

// Tag de string
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Tag de inteiro
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// Tag de lista
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// Obter todas as tags
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

Eventos

Rastreie as ações do usuário para analisar o comportamento e acionar mensagens automatizadas:

// Rastreia um evento de login
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Rastreia um evento de compra
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Preferências de comunicação

Permita que os usuários optem por receber ou não notificações push programaticamente:

// Habilita a comunicação
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Desabilita a comunicação
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Verifica o estado atual
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Gerenciamento de emblemas

Controle o número do emblema do aplicativo nas plataformas suportadas:

// Define o emblema para um número específico
Pushwoosh.Instance.SetBadgeNumber(3);

// Incrementa o emblema
Pushwoosh.Instance.AddBadgeNumber(1);

// Limpa o emblema
Pushwoosh.Instance.SetBadgeNumber(0);

Solução de problemas

Se um push não for entregue, procure o código de erro da sua plataforma em Erros de envio para ver o que ele significa e como corrigi-lo.

Se você encontrar algum problema durante o processo de integração, consulte a seção de suporte e comunidade.