# Coletar dados dos jogadores

O Pushwoosh precisa saber quem são os seus jogadores e o que eles fazem no jogo. Os eventos registram as ações, e as tags guardam o estado atual de cada jogador.

<Aside type="tip" title="Deixe o AI Assistant criar os eventos e as tags">
O [AI Assistant](/pt/product/pushwoosh-ai/ai-assistant/) pode criar no seu aplicativo os eventos e as tags desta página. Envie a ele o link da página e peça que torne as tags User-specific. Confira cada alteração antes de aprová-la.
</Aside>

<span id="identify-players-by-user-id" />

## Identificar os jogadores pelo User ID

<Aside type="caution" icon="setting" title="Assistência de desenvolvedor necessária">
Definir o User ID é uma alteração no código do seu jogo. Compartilhe [Coleta de User IDs](/pt/developer/first-steps/collecting-user-ids/#setuserid-sdk-method) com os seus desenvolvedores.
</Aside>

O Pushwoosh vincula todos os dispositivos de um jogador a um único User ID, para que os seus segmentos e Journeys tratem uma pessoa como um único jogador. Os eventos e as tags User-specific que um dispositivo registrou antes de o jogador fazer login ficam com o ID anterior dele. As tags Device-specific acompanham o dispositivo.

Por padrão, o Pushwoosh usa o ID de hardware (HWID) de cada dispositivo como o User ID dele. Assim, um jogador que joga em dois dispositivos conta como dois jogadores. Para evitar isso com os jogadores que fazem login, defina o seu próprio ID de conta como o User ID deles:

1. Escolha o ID a ser usado. Use o ID de conta que o seu jogo já atribui a cada jogador.
2. Peça aos seus desenvolvedores que chamem `setUserId` com esse ID quando o jogador fizer login.
3. Confira o resultado. Faça login no jogo em um dispositivo de teste, depois abra **Público** → **Explorador de usuários**, pesquise por **ID do Usuário** e insira o ID de conta. O perfil do jogador é aberto.

Os jogadores que nunca fazem login mantêm o HWID como User ID, e o Pushwoosh o define para eles.

Para saber mais sobre como os User IDs se relacionam com os dispositivos, consulte [Usuários (User IDs)](/pt/product/pushwoosh-knowledge-hub/users-userids/).

<span id="set-up-the-events-to-track" />

## Configurar os eventos a serem rastreados

É pelos eventos que o Pushwoosh fica sabendo o que um jogador faz. Crie-os primeiro: os [segmentos](/pt/tutorials/industry-playbooks/mobile-games/build-the-segments/) agrupam os jogadores pelos eventos que eles acionaram, e as [Journeys](/pt/tutorials/industry-playbooks/mobile-games/build-the-journeys/) começam quando um evento acontece.

Planeje os eventos e os atributos deles antes de criar qualquer coisa. [Eventos recomendados para aplicativos de jogos](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/) lista eventos de jogos prontos com atributos, e [Eventos personalizados](/pt/product/audience-data-and-segmentation/events/custom-events/) explica como definir os seus.

Há dois tipos de eventos:

* [Eventos padrão](#default-events): registro do dispositivo, abertura do aplicativo, compra e alguns outros. O SDK os envia, e você não precisa criá-los no Painel de Controle.
* [Eventos personalizados](#custom-events): nível concluído, recompensa resgatada, loja aberta e outros. Os seus desenvolvedores [os enviam do jogo](#send-the-events-from-the-game), e o Pushwoosh cria cada um na primeira vez que ele chega. Para escolher você mesmo os tipos dos atributos, crie primeiro o evento no Painel de Controle. Consulte [Eventos personalizados](/pt/product/audience-data-and-segmentation/events/custom-events/) e [Eventos criados automaticamente](/pt/product/audience-data-and-segmentation/events/#events-created-automatically).

<span id="default-events" />

### Eventos padrão

O SDK envia esses eventos por você. Você precisa deles para a maioria das Journeys deste playbook: onboarding, recuperação e ofertas de compra.

* [`PW_DeviceRegistered`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_deviceregistered): um dispositivo recebeu o seu primeiro token de push. O SDK solicita o token somente quando o jogo chama `registerForPushNotifications`, que no iOS também mostra a solicitação de permissão, e o token chega qualquer que seja a resposta do jogador. Se o jogo pedir a permissão depois da primeira abertura, o evento é disparado nesse momento, e não na instalação. Para identificar novos jogadores, use o evento `Tutorial started` em vez dele.
* [`PW_ApplicationOpen`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_applicationopen): um jogador abriu o jogo. Você precisa dele para encontrar os jogadores que ainda jogam e os que pararam de jogar, para poder recuperá-los.
* [`PW_InAppPurchase`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_inapppurchase): um jogador comprou algo no jogo. Você precisa dele para distinguir pagantes de não pagantes, por exemplo, para oferecer uma primeira compra apenas a jogadores que nunca pagaram. Os seus desenvolvedores ativam o rastreamento de compras no SDK do iOS ou enviam as compras pelo código, e no Android sempre as enviam pelo código. No iOS, ele é disparado apenas para produtos configurados no App Store Connect.
* Opcional: [`PW_UserIdle`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_useridle): é disparado quando um jogador para de tocar na tela por um tempo definido por você, de pelo menos 30 segundos. Inicia uma Journey que mostra uma dica in-app quando um jogador fica travado. Os seus desenvolvedores o ativam na configuração do SDK.
* Opcional: [`PW_ApplicationExit`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_applicationexit): é disparado quando um jogador sai do jogo e não volta em 10 a 30 segundos. Inicia uma Journey de recuperação para jogadores que saem no meio de um fluxo. Os seus desenvolvedores o ativam na configuração do SDK.

Um evento aparece em **Público** → **Eventos** depois que o SDK o envia pela primeira vez.

Para adicionar antes à lista qualquer outro evento padrão, por exemplo, para criar um segmento antes de a atualização do jogo ser lançada:

1. Abra **Público** → **Eventos** e clique em **Criar evento**.
2. Escolha **Evento Padrão**.
3. Selecione o evento e clique em **Ativar**.

A lista da etapa 3 não inclui `PW_UserIdle` e `PW_ApplicationExit`. Eles aparecem em **Público** → **Eventos** somente depois que o SDK os envia pela primeira vez.


Para obter detalhes sobre esses e outros eventos padrão, consulte [Eventos padrão](/pt/product/audience-data-and-segmentation/events/default-events/).

<span id="custom-events" />

### Eventos personalizados

Os eventos personalizados registram o que acontece no seu jogo, como concluir um nível. Você escolhe quais o jogo precisa, os seus desenvolvedores os enviam, e você confere se eles estão chegando.

<span id="choose-the-events-to-track" />

#### Escolher os eventos a serem rastreados

Escolha os eventos de que o seu jogo precisa e os atributos que cada um carrega, por exemplo, `level_id` para `Level completed`. A tabela traz exemplos: use-os como estão, renomeie-os ou adicione os seus. Rastreie apenas os eventos necessários para as Journeys que você lançar.

| Evento | Quando é disparado | Atributos principais | Para que serve |
| --- | --- | --- | --- |
| [New level](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#new-level) | O jogador chega a um novo nível | `level_id` (String) | Opcional: os seus próprios segmentos de marcos |
| [Level completed](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#level-completed) | O jogador conclui um nível | `level_id` (String) | Segmentos de jogadores engajados não pagantes e de jogadores travados, Journey de ajuda para jogadores travados |
| Level failed | O jogador falha em um nível | `level_id` (String) | Segmento e Journey de jogadores travados |
| Tutorial started | O jogador inicia o tutorial do jogo | `tutorial_name` (String) | Journey de onboarding, segmento de abandono do tutorial |
| [Tutorial completed](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#tutorial-completed) | O jogador conclui o tutorial do jogo | `tutorial_name` (String), `completion` (Boolean) | Journey de onboarding, fluxo de permissão de push |
| [Virtual currency earned](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#virtual-currency-earned) | O saldo de moeda do jogo do jogador aumenta | `currency_name` (String), `quantity` (Integer) | Opcional: os seus próprios segmentos baseados em moeda |
| [Achievement unlocked](/pt/product/audience-data-and-segmentation/events/recommended-events-for-gaming-apps/#achievement-unlocked) | O jogador desbloqueia uma conquista | `achievement_name` (String), `level` (Integer) | Segmento de caçadores de conquistas |
| Daily reward claimed | O jogador resgata a recompensa diária | `day_number` (Integer) | Journey de lembrete da recompensa diária |
| Live event joined | O jogador entra em um evento ao vivo | `event_id` (String) | Meta de conversão da Journey do evento ao vivo |
| Store opened | O jogador abre a loja do jogo | `section` (String) | Journey de abandono da loja |

<Aside type="tip" title="O seu jogo não tem tutorial?">
Use os seus próprios eventos para as duas primeiras ações de todo novo jogador, como iniciar e concluir o primeiro nível, em vez de `Tutorial started` e `Tutorial completed` sempre que este playbook os mencionar.

* O primeiro evento inicia a Journey de onboarding, e o segundo informa a ela que o jogador terminou. Ignore a condição `completion` que acompanha `Tutorial completed`.
* Os SDKs não enviam nenhum evento próprio de primeira abertura, então ambos precisam ser eventos personalizados enviados pelo seu jogo.
</Aside>

<span id="send-the-events-from-the-game" />

#### Enviar os eventos do jogo

<Aside type="caution" icon="setting" title="Assistência de desenvolvedor necessária">
Enviar eventos é uma alteração no código do seu jogo. Compartilhe [Eventos para desenvolvedores](/pt/developer/guides/audience-and-segmentation/events/) e os [exemplos de eventos de jogos](/pt/developer/guides/audience-and-segmentation/events/custom-events-examples#gaming-apps) com os seus desenvolvedores. Eles enviam cada evento com `postEvent` no momento em que a ação acontece. Compras e concessões de recompensas devem vir do servidor do jogo com o `userId` do jogador.
</Aside>

Combine com os seus desenvolvedores quais eventos o jogo envia e quais atributos cada um carrega. Os nomes dos eventos e dos atributos precisam coincidir exatamente.

Por exemplo, é assim que o jogo envia `Level completed` com o atributo `level_id`:

<Tabs>
<TabItem label="Android">
```java
TagsBundle attributes = new TagsBundle.Builder()
    .putString("level_id", "12")
    .build();

InAppManager.getInstance().postEvent("Level completed", attributes);
```
</TabItem>
<TabItem label="iOS">
```swift
PWInAppManager.shared().postEvent("Level completed", withAttributes: ["level_id": "12"])
```
</TabItem>
</Tabs>

Se um evento acontece em um servidor que já envia os próprios webhooks, como o backend do seu jogo ou um serviço de torneios, ele pode chegar ao Pushwoosh por meio de um [webhook de entrada](/pt/product/integrations/inbound-webhook/) em vez de `postEvent`. Você mapeia os campos que ele envia para um evento do Pushwoosh no Painel de Controle, e o evento pode iniciar uma Journey como qualquer outro.

Para conferir se um evento chegou, abra **Público** → **Explorador de usuários**, encontre um jogador de teste e abra a aba **Histórico de eventos**.


<span id="track-revenue-as-pw_conversion" />

### Rastrear a receita como PW_Conversion

`PW_Conversion` registra o valor e a moeda de cada compra em um único formato. Você precisa dele para uma meta de receita nas Journeys e para as faixas de gasto na [Segmentação RFM](/pt/product/audience-data-and-segmentation/segmentation/rfm-segmentation/), que agrupa os jogadores por quão recentemente, com que frequência e quanto eles compram.

As compras que o SDK do iOS rastreia chegam ao `PW_Conversion` sozinhas, porque carregam os atributos `__amount` e `__currency`. As compras do Android precisam de uma destas opções:

* Se o seu jogo roda no iOS e no Android, peça aos seus desenvolvedores que enviem as compras do Android como `PW_InAppPurchase` com os atributos numéricos `__amount` e `__currency` por meio de `postEvent`, em vez do método de compra do SDK. Assim, o mesmo mapeamento automático cobre as duas plataformas.
* Se o seu jogo roda apenas no Android, mapeie as compras você mesmo, sem código novo. Um evento mantém um único mapeamento, então, em um jogo com compras no iOS, um mapeamento manual substituiria o automático.

Para mapear as compras você mesmo:

1. Abra **Público** → **Eventos** e abra as configurações de eventos de conversão.
2. Adicione `PW_InAppPurchase` como evento de conversão.
3. Selecione os atributos que contêm o **Preço** e a **Moeda** dele.
4. Clique em **Aplicar**.

<Aside type="caution">
Use apenas um caminho por transação. Se o seu código também enviar `PW_Conversion` para a mesma compra, o Pushwoosh registrará dois eventos de conversão separados.
</Aside>

Para ver todas as opções de configuração, consulte [Eventos de conversão](/pt/product/audience-data-and-segmentation/events/conversion-events/).

<span id="track-subscriptions-from-the-stores" />

### Rastrear as assinaturas das lojas

Se o seu jogo vende assinaturas, como um passe VIP ou um passe de batalha, o Pushwoosh recebe as mudanças de status delas da App Store e do Google Play. Cada mudança chega como um evento `PW_Subscription*`, por exemplo:

* `PW_SubscriptionStart`: um jogador faz a assinatura.
* `PW_SubscriptionCancel`: um jogador desativa a renovação automática.
* `PW_SubscriptionBillingIssue`: um pagamento de renovação falha.

Use esses eventos para iniciar Journeys, por exemplo, um lembrete antes de um passe cancelado expirar.

<Aside type="caution" icon="setting" title="Assistência de desenvolvedor necessária">
O jogo precisa passar o HWID do Pushwoosh do jogador em cada compra:

* No iOS, como `appAccountToken`.
* No Android, como `obfuscatedAccountId`. O jogo passa o valor de `getSubscriptionAccountId()` do SDK, que é o Application Code e o HWID juntos, e não apenas o HWID.

Sem isso, o Pushwoosh recebe a notificação, mas não registra nenhum evento, e as assinaturas compradas antes não poderão ser associadas depois. Compartilhe [Rastreamento de assinaturas da App Store](/pt/product/integrations/app-store-subscription-tracking/) e [Rastreamento de assinaturas do Google Play](/pt/product/integrations/google-play-subscription-tracking/) com os seus desenvolvedores.
</Aside>

Os eventos cobrem apenas assinaturas. Compras únicas, como um pacote de moedas, continuam chegando como `PW_InAppPurchase`.

<span id="store-player-data-in-tags" />

## Armazenar dados dos jogadores em tags

Uma [tag](/pt/product/audience-data-and-segmentation/user-data-tags/) é um valor que o Pushwoosh armazena no perfil de um jogador, como o nível dele ou se ele já pagou. Um evento registra o que aconteceu, e uma tag guarda o estado atual. As tags ajudam você a:

* Enviar uma mensagem apenas aos jogadores com um determinado valor, por exemplo, uma oferta apenas aos jogadores pagantes.
* Inserir o valor no texto da mensagem, por exemplo, o nível do jogador. Consulte [Criar as Journeys](/pt/tutorials/industry-playbooks/mobile-games/build-the-journeys/).

As tags são opcionais. As Journeys deste playbook funcionam com eventos e com tags padrão que o próprio Pushwoosh define, então, no início, você pode dispensar as suas próprias tags. Adicione-as quando quiser mais formas de agrupar os jogadores. Consulte [Segmentos por tags](/pt/tutorials/industry-playbooks/mobile-games/build-the-segments/#segments-by-tags).

### As suas próprias tags

Os seus desenvolvedores enviam os valores das tags do jogo, ou você pode [importá-los de um arquivo CSV](/pt/product/audience-data-and-segmentation/user-data-tags/update-tags-via-csv/). O Pushwoosh cria uma tag na primeira vez que os seus desenvolvedores a enviam, como uma tag User-specific. Crie primeiro a tag no Painel de Controle se quiser escolher você mesmo o tipo dela. Consulte [Gerenciar dados de usuários com tags](/pt/product/audience-data-and-segmentation/user-data-tags/tags/).

Estas tags são exemplos. Renomeie-as de acordo com o vocabulário do seu jogo e adicione as suas:

| Tag | Tipo | Exemplo | Para que serve |
| --- | --- | --- | --- |
| `player_level` | Integer | `12` | Filtrar mensagens por faixa de progresso |
| `is_paying_user` | Boolean | `true` | Separar as mensagens para pagantes e não pagantes |
| `soft_currency_balance` | Integer | `1500` | Oferecer um pacote de moedas aos jogadores com saldo baixo |
| `vip_tier` | String | `gold` | Dar aos jogadores VIP ofertas exclusivas e acesso antecipado |
| `favorite_mode` | String | `pvp` | Anunciar eventos ao vivo para o modo de que o jogador gosta |

Ao criar uma tag no Painel de Controle, mantenha [**Específico do usuário**](/pt/product/audience-data-and-segmentation/user-data-tags/tags/#tag-scope-general-vs-user-specific) ativado, como vem por padrão. Assim, o Pushwoosh mantém um valor por User ID, de modo que o valor pertence ao jogador, e não a um dos dispositivos dele. Com **Específico do usuário** desativado, cada dispositivo mantém o próprio valor. Consulte [Identificar os jogadores pelo User ID](/pt/tutorials/industry-playbooks/mobile-games/collect-player-data/#identify-players-by-user-id).

### Tags padrão

O Pushwoosh armazena estas [tags padrão](/pt/product/audience-data-and-segmentation/user-data-tags/tags/#default-tags) para cada dispositivo, então você não precisa criá-las:

* **Language**: o idioma do dispositivo. O Pushwoosh o usa para enviar a cada jogador a mensagem no idioma dele.
* **Last Application Open**: quando o jogo foi aberto pela última vez no dispositivo. Use-a para encontrar os jogadores que pararam de jogar.
* **Push Alerts Enabled**: se as notificações estão permitidas nas configurações do dispositivo. Use-a para mostrar uma mensagem in-app apenas aos jogadores que ainda não as permitiram.
* **First Install**: quando o jogo foi instalado pela primeira vez no dispositivo. Use-a para aniversários de instalação.
* **Country**: o país do dispositivo. Use-a para enviar uma oferta ou um anúncio de evento ao vivo apenas aos jogadores de uma região.