# Tags As Tags são uma das ferramentas mais úteis que o Pushwoosh oferece, permitindo uma gama de funcionalidades sofisticadas. Ao usar tags, você pode segmentar seu público e enviar notificações push direcionadas a usuários específicos com base em seus atributos. As Tags podem conter quaisquer dados arbitrários associados a um usuário ou dispositivo específico. Esses dados podem incluir nomes de usuário, IDs, cidades, times de futebol favoritos, categorias de notícias preferidas ou qualquer outra informação relevante sobre seus usuários. ## Decidindo quais tags usar Comece identificando as necessidades do seu negócio e determinando como você deseja segmentar seu público. Considere fatores como idade, localização, histórico de compras no aplicativo ou qualquer outro critério relevante para direcionar os usuários. ## Valores de tag Os valores de tag podem ajudá-lo a tornar suas campanhas de push mais inteligentes. Cada tag é capaz de armazenar um _número quase ilimitado de valores_. Basicamente, isso significa que uma única tag seria suficiente para registrar um tipo específico de informação sobre cada usuário final em seu banco de dados. Existem apenas algumas tags disponíveis para cada conta, mas considerando o espaço quase infinito para cada tag, apenas algumas tags são suficientes para coletar uma enorme quantidade de informações sobre seus usuários e configurar padrões de direcionamento muito complexos. ## Tipos de tags * **Inteiro** — usado para dados inteiros (quantidade de dinheiro no jogo adquirida, nível alcançado, idade). * **String** — usado para valores de texto (nome de usuário, e-mail, identificadores). * **Lista** — o mesmo que o tipo String, mas cada usuário pode ter vários valores definidos simultaneamente (preferências musicais, categorias de notícias, preferências de culinária). * **Booleano** — tipo de Tag verdadeiro / falso. * **Data** — usado para datas de calendário. Basicamente, este é um tipo de tag inteiro que armazena timestamps Unix Epoch (convertidos automaticamente de/para a data gregoriana). * **Preço** — permite definir valores de acordo com a moeda especificada no formato “\*.XX” [Saiba mais](https://en.wikipedia.org/wiki/ISO\_4217). * **Versão** — usado para versionamento. O exemplo de formato permitido é w.x.y.z (Major.Minor.Patch.Build). O valor máximo para cada parte da versão é 9999, então o número máximo da versão não pode ser maior que 9999.9999.9999.9999. ### Operadores de tag Cada tipo de Tag tem um conjunto específico de **operadores** aplicáveis. Os operadores de tag definem a relação entre a Tag e seus valores para fins de segmentação. * Operadores de Tag Inteiro: `is`, `is not`, `are`, `not in`, `not set`, `any` * Operadores de Tag String: `is`, `is not`, `are`, `not in`, `not set`, `any` * Operadores de Tag Lista: `in`, `not in`, `not set`, `any` * Operadores de Tag Booleano: `is` (true/false), `not set`, `any` * Operadores de Tag Data: `exactly on`, `on or after`, `on or before`, `between`, `not set`, `any` * Operadores de Tag Preço: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any` * Operadores de Tag Versão: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any` ## Escopo da tag: Geral vs. Específico do usuário Ao criar uma tag, você escolhe como seus valores são armazenados: - **Geral** (padrão, `user_specific: false`): o valor da tag é armazenado por dispositivo (HWID). Cada dispositivo do mesmo usuário pode ter um valor diferente de forma independente. - **Específico do usuário** (`user_specific: true`): o valor da tag é armazenado por usuário (UserID). Quando definido via UserID, o valor é aplicado a todos os dispositivos do usuário de uma só vez. Útil para atributos que pertencem à pessoa, não a um dispositivo específico: nível de assinatura, pontos de fidelidade, idioma preferido. ### Exemplo Um usuário tem as versões iOS e Android do seu aplicativo instaladas. Definir uma tag `subscription_tier` como `"premium"` através do UserID dele a aplica a ambos os dispositivos imediatamente. Com uma tag Geral, você precisaria defini-la por dispositivo separadamente. ```javascript title="Exemplo: definir uma tag específica do usuário via UserID" { "request":{ "application": "XXXXX-XXXXX", "userId": "the id of a specific user", "tags": { "subscription_tier": "premium", "loyalty_points": 350 } } } ``` ## Tags padrão Essas tags estão disponíveis no Pushwoosh por padrão, então você não precisa (e, na verdade, não deve) configurá-las manualmente. A maioria delas é definida a partir do aplicativo e enviada para nosso servidor através de [`registerDevice`](/pt/developer/api-reference/device-api/) e outras chamadas de API, e algumas são definidas pelo próprio servidor. | Nome | Tipo | Onde é definido | Descrição | | ------------------------- | ------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application Version | Versão | SDK | Versão atual do aplicativo instalada em um dispositivo | | Browser Type | String | SDK | Quando um dispositivo é registrado para o seu projeto web, seu tipo – móvel ou desktop – é rastreado automaticamente | | City | String | Servidor | Última localização geográfica registrada de um dispositivo | | Country | String | Servidor | Última localização geográfica registrada de um dispositivo | | Device Model | String | SDK | Indica o modelo do dispositivo onde o aplicativo está instalado | | First Install | Data | Servidor | Indica a data em que um dispositivo foi registrado para notificações pela primeira vez | | In-App Product | Lista | SDK | Os produtos in-app comprados por um usuário do aplicativo | | Last In-App Purchase Date | Data | SDK | A data da última compra in-app feita em um dispositivo | | Language | String | SDK | Abreviação de duas letras em minúsculas da localidade de um dispositivo de acordo com a ISO-639-1; obtida das configurações do dispositivo | | Last Application Open | Data | Servidor | A hora do lançamento mais recente do aplicativo em um dispositivo | | Last Email Open | Data | Servidor | A data em que o endereço de e-mail do dispositivo registrou mais recentemente um evento de abertura de e-mail | | Last Email Open Message Code | String | Servidor | [Código da mensagem](/pt/developer/api-reference/api-identifiers#message-code) do e-mail aberto mais recentemente (formato `XXXX-XXXXXXXX-XXXXXXXX`). Atualizado em cada evento [`PW_EmailOpen`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_emailopen). Use-o para segmentar destinatários de uma campanha de e-mail específica por quem a abriu | | Last Email Click | Data | Servidor | A data em que o endereço de e-mail do dispositivo registrou mais recentemente um clique em um link de e-mail | | Last Email Click Message Code | String | Servidor | [Código da mensagem](/pt/developer/api-reference/api-identifiers#message-code) do e-mail mais recente em que um link foi clicado (formato `XXXX-XXXXXXXX-XXXXXXXX`). Atualizado em cada evento [`PW_EmailLinkClicked`](/pt/product/audience-data-and-segmentation/events/default-events/#pw_emaillinkclicked). Use-o para segmentar destinatários de uma campanha de e-mail específica por quem clicou | | Last Email Confirm | Data | Servidor | A data da confirmação de assinatura Double Opt-In mais recente para o endereço de e-mail do dispositivo | | Bounced Email | Data | Servidor | A data em que ocorreu um hard bounce para este endereço de e-mail. Armazenado como Data para permitir a segmentação baseada em tempo, por exemplo, para excluir usuários com bounces recentes | | Unsubscribed Emails | Booleano | SDK | Indica se um usuário cancelou a inscrição para receber e-mails do seu aplicativo | | OS Version | Versão | SDK | A versão de um sistema operacional em execução em um dispositivo | | Platform | String | SDK | A plataforma na qual o usuário está usando seu projeto. | | Push Alerts Enabled | Booleano | SDK | Indica se os alertas de push são permitidos nas configurações do dispositivo | | SDK Version | Versão | SDK | A versão do SDK do Pushwoosh implementada em um dispositivo | ## Tags personalizadas É aqui que sua criatividade entra em jogo para alcançar seus objetivos de negócio específicos. Tags personalizadas podem ser criadas com base na lógica de segmentação ou no padrão de direcionamento apropriado para suas necessidades de negócio únicas. Colabore com sua equipe de marketing para definir as tags personalizadas adicionais necessárias para suas campanhas. ### Como configurar uma tag personalizada Você pode adicionar uma nova tag no [Painel de Controle do Pushwoosh](/pt/product/audience-data-and-segmentation/user-data-tags/tags) ou usar o método [`/addTag`](/pt/developer/api-reference/tags#addtag). #### addTag `POST` `https://api.pushwoosh.com/json/1.3/addTag` Cria uma tag em sua conta. #### Corpo da Requisição | Nome | Tipo | Descrição | | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- | | auth* | string | Token de acesso à API do Painel de Controle do Pushwoosh. | | tag* | object | Parâmetros da tag. | | tag.name* | string | Nome da tag. | | tag.type* | integer | Tipo de tag. Veja os valores possíveis abaixo. | | tag.user\_specific | boolean | Quando `true`, o valor da tag é armazenado no nível do usuário e compartilhado entre todos os dispositivos de um usuário quando definido por UserID. Quando `false` (padrão), a tag é no nível do dispositivo e definida por HWID. | ```javascript { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` ```javascript title="Exemplo" { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // obrigatório, token de acesso à API do Painel de Controle do Pushwoosh "tag": { "name": "TAG_NAME", // obrigatório "type": 1, // obrigatório, veja os valores possíveis abaixo "user_specific": false // opcional. true = nível de usuário; false = nível de dispositivo (padrão) } } } ``` **Tipos de valores de tag possíveis:** * 1 - Inteiro * 2 - String * 3 - Lista * 4 - Data * 5 - Booleano * 6 - Decimal. Ex: 19.95 * 7 - Versão. Ex: "1.0.0.0" ### Como coletar informações dos usuários Depois de adicionar e configurar uma tag, ela está pronta para começar a coletar informações de seus usuários. Siga estes passos para implementá-la: 1. Integre o [SDK do Pushwoosh](/pt/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) em seu projeto seguindo o guia de integração relevante. 2. Use a função [`setTags`](/pt/developer/api-reference/device-api/#settags) para atribuir tags e coletar dados do usuário. Abaixo estão exemplos de implementação para diferentes frameworks usando a função [`setTags`](/pt/developer/api-reference/device-api/#settags). ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentação](https://pushwoosh.github.io/pushwoosh-ios-sdk/PushwooshiOS/documentation/pushwooshframework/pushwoosh/settags(_:)/) ```java pushwoosh.setTags(Tags.intTag("intTag", 42)); ``` [Documentação](https://pushwoosh.github.io/pushwoosh-android-sdk/pushwoosh/com.pushwoosh/-pushwoosh/set-tags.html) ``` PushNotification.prototype.setTags = function( config, success, fail ) ``` [Documentação](/pt/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference/#settags) ```dart Future setTags(Map tags) async { await _channel.invokeMethod("setTags", {"tags" : tags}); } ``` [Documentação](https://pub.dev/documentation/pushwoosh_flutter/latest/pushwoosh_flutter/Pushwoosh/setTags.html) ```javascript pushNotification.setTags({ "string_tag" : "Hello world", "int_tag" : 42, "list_tag":["hello", "world"] }); ``` [Documentação](https://github.com/Pushwoosh/pushwoosh-react-native-plugin/blob/master/docs/README.md#settags) ##### **SetIntTag** Define uma Tag de Inteiro para o dispositivo. ```csharp public virtual void SetIntTag(string tagName, int tagValue) ``` ##### **SetStringTag** Define uma Tag de String para o dispositivo. ```csharp public virtual void SetStringTag(string tagName, string tagValue) ``` ##### **SetListTag** Define uma Tag de Lista para o dispositivo. ```csharp public virtual void SetListTag(string tagName, List tagValues) ``` [Documentação](https://github.com/Pushwoosh/pushwoosh-unity/blob/master/Documentation/README.md#pushwoosh) ```cpp FPushwooshModule& pushwoosh = FPushwooshModule::Get(); pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }"); ``` [Documentação](https://github.com/Pushwoosh/pushwoosh-unreal-engine/blob/master/Plugins/Pushwoosh/Documentation/README.md#settags) ```javascript Pushwoosh.setTags({ "key": keyValue, "value": inputValue }); ``` [Documentação](https://github.com/Pushwoosh/pushwoosh-expo-plugin-sample/blob/main/app/_layout.tsx#L296C17-L296C76) ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentação](https://github.com/Pushwoosh/pushwoosh-dotnet/blob/c40c0fd60cb5fe5c5016c46d677a779a5600f45f/PushwooshSDK.DotNet.iOS.Bindings/PushwooshFramework.xcframework/ios-arm64/PushwooshFramework.framework/Headers/PushNotificationManager.h#L380) **Parâmetros de entrada** **Tags** – Uma lista de registros de tag contendo `TagName` e `TagValue`. - `TagName` deve ser sempre do tipo **Text**. - `TagValue` pode ser **Text, Integer, Boolean, Date**, etc. [Saiba mais](/pt/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags) ### Definindo tags via API Embora na maioria dos casos (99%), as tags sejam definidas a partir do aplicativo, você também pode definir tags através da API do Pushwoosh. Abaixo está um exemplo de uma solicitação típica para o endpoint [`/setTags`](/pt/developer/api-reference/device-api#settags): POST `https://api.pushwoosh.com/json/1.3/setTags` ```json { "request": { "application": "XXXXX-XXXXX", // obrigatório, código do aplicativo Pushwoosh "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // obrigatório, ID do dispositivo de hardware usado na API /registerDevice "tags": { // obrigatório "StringTag": "string value", // Exemplo de uma tag de string "IntegerTag": 42, // Exemplo de uma tag de inteiro "ListTag": ["string1", "string2"], // Exemplo de uma tag de lista "DateTag": "2024-10-02 22:11", // Nota: o tempo deve estar em UTC "BooleanTag": true // Valores válidos: true, false } } } ``` [Para mais detalhes, consulte a documentação da API setTags](/pt/developer/api-reference/device-api/#settags) ## Usando a tag padrão **City** A localização do dispositivo é determinada com base em seu endereço IP no momento em que seu aplicativo foi iniciado nesse dispositivo pela última vez. O GeoIP envia os dados de localização para o Pushwoosh, e o Pushwoosh salva a localização recebida do GeoIP como um valor da tag City para um dispositivo específico. Em alguns casos, a localização enviada pelo GeoIP difere do nome da cidade — por exemplo, quando se refere a uma área de uma cidade ou outra unidade administrativa. Por favor, tenha cuidado ao usar a tag City padrão para fins de segmentação: certifique-se de selecionar os valores adequados. Por exemplo, se você pretende direcionar usuários de Munique, você precisa cobrir isso com um conjunto de valores da tag City, incluindo "Munich" em si (com todos os valores correspondentes, como diferentes variantes de grafia que poderiam ser retornadas pelo GeoIP e salvas como valores de tag) e várias áreas próximas.