> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Use Tags de Dados do OneSignal para armazenar propriedades do usuário e rastrear eventos para segmentação avançada e mensagens personalizadas.

Tags de Dados são pares chave-valor que permitem armazenar propriedades personalizadas e rastrear o comportamento do usuário no OneSignal. Elas possibilitam segmentação e personalização poderosas.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/t82DSCUXShk?si=KH_u3zB2N5ci8GLT" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

Use tags para:

* Armazenar características do usuário como `subscription_tier` ou `name`
* Rastrear comportamentos como `purchases`, `clicks` ou `levels`
* Segmentar usuários para mensagens e Jornadas
* Personalizar conteúdo de mensagens

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/Z-rYqwEUU0M?si=Qjx2dMdFXwXSuZJR" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

***

## Regras de formatação de valor de tag de dados

Todos os valores de Tag devem ser **strings**. Você ainda pode armazenar números, timestamps e valores booleanos—apenas converta-os em string!

| Tipo de Valor | Exemplo de Formato                  | Notas                                                                         |
| ------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
| Rótulo String | `"free"`, `"VIP"`                   | Para tipos de usuário, privilégios, status                                    |
| Número        | `"42"`, `"3.14"`                    | Permite filtros numéricos (`maior que`, `menor que`)                          |
| Timestamp     | `"1685400000"`                      | Timestamp Unix (em segundos). Use com [Operadores de Tempo](./time-operators) |
| Booleano      | `"true"` / `"false"`, `"1"` / `"0"` | Use `"1"`/`"0"` para reduzir o tamanho da carga                               |

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/YTp-jLcajJ0?si=uSRn2cQ7Yur5MAp0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

<Warning>
  **Não suportado:** Arrays, objetos, valores aninhados ou blobs JSON. Se você precisar armazenar dados complexos, use [Eventos Personalizados](./custom-events).
</Warning>

### Palavras-chave restritas

As seguintes palavras-chave são restritas e não devem ser usadas como chaves de tag porque são usadas internamente para personalização de mensagens:
`message`, `notification`, `subscription`, `user`, `template`, `app`, `org`, `dynamic_content`, `data_feed`, `journey`, `custom_data`

Consulte [Personalização de Mensagens](./message-personalization) para mais detalhes.

### Tags vs Eventos Personalizados

[Tags](/docs/pt-BR/add-user-data-tags) e [Custom Events](/docs/pt-BR/custom-events) são ambas formas de adicionar dados aos seus usuários. No entanto, existem algumas diferenças principais:

| Recurso           |                     Tags                     |                                            Custom Events                                            |
| ----------------- | :------------------------------------------: | :-------------------------------------------------------------------------------------------------: |
| Uso de dados      |         Segmentação e personalização         | Disparar Jornadas sem um Segmento, passos Wait Until, personalização diretamente dentro de Jornadas |
| Retenção de dados |                   Vitalícia                  |    30+ dias ([armazenamento vitalício está disponível](/docs/pt-BR/billing-faq#streaming-events))   |
| Formato de dados  |        Strings ou números chave-valor        |                                                 JSON                                                |
| Fonte de dados    | OneSignal SDK, API ou integrações (limitado) |                                  OneSignal SDK, API ou integrações                                  |
| Acesso aos dados  |   Segmentação e personalização de mensagem   |            Jornadas e personalização de Journey-message-template, Segmentação (Em breve)            |

A principal distinção entre Tags e Custom Events está em sua profundidade e casos de uso. Tags são propriedades de um usuário, como Nome, Status de Conta ou Localização. Eventos são coisas que o usuário fez, como Comprar um Item, Completar um Nível ou Convidar um Amigo. Tanto tags quanto eventos podem ser usados para segmentação e personalização.

Na prática, você provavelmente usará ambos:

* Tags para propriedades de usuário que são estáticas e não mudam frequentemente
* Custom Events para cenários em tempo real, segmentação complexa e fluxos de trabalho de jornada mais sofisticados

***

## Estratégias de tags recomendadas

Tags de Dados devem representar informações que você deseja **usar em mensagens ou segmentação de público**. Elas não são destinadas a armazenar perfis completos de usuário ou logs—use seu banco de dados backend para isso.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/DeCnQYA21TY?si=YnAv50tpiiVdNEX7" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

### Tags de comportamento baseadas em eventos

Rastreie ações do usuário com tags. Ótimas para acionar Jornadas, acompanhamentos ou lembretes.

| Chave             | Exemplo de Valor           | Descrição                                                                                         |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `cart_update`     | `"1685400000"`             | Última vez que o usuário adicionou algo ao carrinho. Use [Operadores de Tempo](./time-operators). |
| `last_order`      | `"1684100000"`             | Timestamp da última compra concluída                                                              |
| `amount_spent`    | `"100"`                    | Total gasto—número em string, sem símbolo de moeda                                                |
| `social_share`    | `"2"`                      | Contagem de compartilhamentos sociais ou indicações                                               |
| `tutorial_status` | `"step2"` ou `"completed"` | Progresso do tutorial—use valores de string legíveis ou numerados                                 |

### Tags de atividade de jogo

Usadas por jogos para personalizar com base no desempenho do usuário.

| Chave        | Exemplo de Valor | Descrição                        |
| ------------ | ---------------- | -------------------------------- |
| `points`     | `"1250"`         | Pontos de experiência ou do jogo |
| `level`      | `"8"`            | Nível atual do jogo              |
| `high_score` | `"3000"`         | Maior pontuação alcançada        |

### Tags de status de conta

Use estas para direcionar usuários por nível de conta ou mudança de status.

| Chave             | Exemplo de Valor        | Descrição                          |
| ----------------- | ----------------------- | ---------------------------------- |
| `user_type`       | `"free"`, `"premium"`   | Nível de assinatura ou acesso      |
| `has_downgraded`  | `"1"` ou `"1685400000"` | Booleano ou timestamp do downgrade |
| `user_privileges` | `"admin"`, `"guest"`    | Segmentação baseada em função      |

<Note>
  Use **ID Externo** para identificar usuários individuais. **Não** use tags para esse propósito. Consulte [ID Externo](./users#external-id) e [Aliases](./aliases).
</Note>

### Tags de personalização

Ótimas para personalização de mensagens baseadas em nome usando [Substituição de Variável](./message-personalization).

| Chave        | Exemplo de Valor  | Descrição                        |
| ------------ | ----------------- | -------------------------------- |
| `first_name` | `"Jon"`           | Primeiro nome                    |
| `last_name`  | `"Smith"`         | Sobrenome                        |
| `user_name`  | `"PokeCatcher22"` | Nome de exibição ou nome de tela |

### Tags de localização e demográficas

Segmente usuários por região ou idade.

| Chave        | Exemplo de Valor | Descrição                                                                                    |
| ------------ | ---------------- | -------------------------------------------------------------------------------------------- |
| `region`     | `"New York"`     | Área metropolitana, opcionalmente use [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) |
| `postcode`   | `"94105"`        | CEP ou código postal                                                                         |
| `location`   | `"Downtown LA"`  | Localização string personalizada                                                             |
| `birthdate`  | `"915148800"`    | Timestamp Unix em segundos (data de nascimento)                                              |
| `birth_year` | `"1998"`         | Ano de nascimento de quatro dígitos                                                          |
| `age_range`  | `"18-35"`        | Útil para segmentação geral de público                                                       |

## Como adicionar, atualizar e remover Tags

Você pode gerenciar Tags usando qualquer um dos métodos abaixo, dependendo do seu caso de uso e configuração técnica.

<Frame>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/e5B3nJyr_ao?si=PfVu4bHMkQJydc41" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
</Frame>

<br />

<Columns cols={2}>
  <Card title="Métodos SDK (Recomendado)">
    Defina tags em tempo real do seu aplicativo ou site conforme os usuários executam ações.

    * → [Referência SDK Móvel](./mobile-sdk-reference#data-tags)
    * → [Referência SDK Web](./web-sdk-reference#data-tags)
  </Card>

  <Card title="REST API" href="/reference/update-user">
    Adicione, atualize ou remova tags do lado do servidor usando nossa REST API.
  </Card>

  <Card title="Jornadas" href="./journeys-overview">
    Aplique tags automaticamente conforme os usuários avançam pelas etapas da Jornada.
  </Card>

  <Card title="Importação CSV" href="./import">
    Atualize tags de usuário em massa enviando um CSV com `external_id` ou `subscription_id`.
  </Card>

  <Card title="Prompts de Categoria Web" href="./permission-requests">
    Solicite que os usuários selecionem interesses, que são armazenados como tags.
  </Card>

  <Card title="Mensagens no Aplicativo" href="./in-app-messages-setup">
    Colete ou atualize tags com base em ações de clique em mensagens no aplicativo.
  </Card>

  <Card title="Entrada Manual">
    Edite tags diretamente do Painel OneSignal.

    * Vá para **Público > Usuários > Perfil do Usuário > Tags**
  </Card>

  <Card title="Integrações de Terceiros" href="./integrations">
    Algumas integrações suportam sincronização automática de tags.

    * Segment, HubSpot, Mixpanel e outros
  </Card>
</Columns>

***

## FAQ

### Quantas tags posso definir por usuário?

Depende do seu plano. Consulte os [limites do seu plano](https://onesignal.com/pricing) ou [entre em contato com vendas](https://onesignal.com/contact) para aumentar sua cota.

### O que acontece com minhas tags se eu exceder os limites do plano?

Não há limite para o número de tags disponíveis dentro de um aplicativo OneSignal. O limite se aplica a quantas tags podem ser definidas em cada usuário individual por vez.

Você **não pode adicionar ou atualizar** tags para usuários que estão no ou acima do limite. Você deve excluir tags primeiro, depois enviar uma segunda solicitação para adicionar novas.

Tags já definidas persistirão.

Exemplo:

Limite do seu plano = 20 tags/usuário.

* Usuário tem 19 tags:
  * ✅ Adicionar 1 nova tag = sucesso
  * ❌ Adicionar 2+ novas tags = falha
* Usuário tem 20 tags:
  * ❌ Adicionar qualquer nova tag = falha
  * ✅ Atualizar 1+ tag existente = sucesso

### Onde posso verificar o uso de tags?

* Painel: **Público > Usuários > coluna Tags**
* [Exportar usuários](./exporting-data) para uma visualização completa

### Como reduzo o uso de tags?

* Remova tags usando SDK ou API
* Use [Importação CSV](./import) para excluir em massa
* Use menos tags mais reutilizáveis (ex: `status:active`)

<Info>
  Precisa de ajuda?

  Converse com nossa equipe de Suporte ou envie email para `support@onesignal.com`

  Por favor inclua:

  * Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  * Seu OneSignal App ID
  * O External ID ou Subscription ID se aplicável
  * A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  * Quaisquer [logs ou mensagens de erro](/docs/pt-BR/capturing-a-debug-log) relevantes

  Estamos felizes em ajudar!
</Info>

***