Linguagem de segmentação

A Pushwoosh oferece um poderoso motor de segmentação para construir Segmentos granulares com base nos valores de Tag. A Linguagem de Segmentação é uma forma específica de escrever e combinar critérios de segmentação para descrever um grupo particular de usuários que correspondem a esses critérios e tratá-los como um único segmento de público.

Este artigo descreve os conceitos básicos e a sintaxe da Linguagem de Segmentação e fornece exemplos abrangentes de construção de critérios de segmentação para vários casos.

Conceitos básicos

Cada dispositivo em sua base de usuários tem atributos específicos associados a ele por meio de valores de Tag.

Por exemplo, digamos que uma usuária chamada Jane mora em Tóquio e sua idade é 28. Essa usuária terá as seguintes Tags definidas para seu dispositivo:

• Nome: Jane
• Cidade: Tóquio
• Idade: 28

Para segmentar a Jane, você precisará descrever um segmento da seguinte forma:

T("Name", eq, "Jane") * T("Age", eq, 28) * T("City", eq, "Tokyo")

Essa combinação de condições é uma expressão de filtro usada na Linguagem de Segmentação para descrever grupos de usuários, também conhecidos como Segmentos de público.

Expressões de filtro

A expressão de filtro é uma string que contém uma condição ou uma combinação de condições que descrevem o segmento que você precisa.

Condições

Cada condição descreve um segmento de dispositivos que correspondem aos critérios especificados nessa condição.

Por exemplo, a seguinte condição constrói um segmento de usuários que moram em Tóquio:

T("City", e, "Tokyo")

onde

• T é uma Tag (tipo de condição);
• eq é um operador a ser aplicado;
• “Tokyo” é um valor de Tag que os usuários têm associado aos seus dispositivos.

Tipos de condição

Os seguintes tipos de condição estão disponíveis para segmentação:

• A (Application) – descreve um segmento de dispositivos com um aplicativo específico instalado. Aliases: App, Application;
• T (Tag) – descreve um segmento de dispositivos com os valores de Tag especificados;
• AT (App-scoped tag) – procura um valor de tag dentro de um aplicativo específico; o código do aplicativo é necessário como primeiro argumento. Alias: Tag;
• Event – descreve um segmento de dispositivos que acionaram um evento específico da Pushwoosh;
• Geo – descreve um segmento de dispositivos dentro de um raio geográfico específico;
• BTTS – descreve um segmento de dispositivos com base no melhor horário para enviar;
• Updated – descreve um segmento de dispositivos com base em seu último carimbo de data/hora de atualização;
• Segment – referencia outro filtro/segmento por seu código;

Operações com condições

Para construir segmentos sofisticados, as seguintes operações podem ser aplicadas às condições dentro da expressão de filtro:

União (+)

Junta os segmentos, ou seja, constrói um novo segmento de usuários que correspondem a pelo menos uma das condições especificadas.

Por exemplo, para segmentar usuários que moram em Tóquio ou em Osaka, você precisará descrever o segmento com as seguintes condições:

T("City", eq, "Tokyo") + T("City", eq, "Osaka")

Nota

Equivalente à disjunção lógica (OR). Também pode ser escrito como operador or.

Interseção (*)

Constrói um segmento de usuários que pertencem a ambos os segmentos descritos pelas condições. Assim, apenas os usuários que cumprem cada condição que você especificar serão incluídos.

A seguinte expressão descreve um segmento de usuários que moram em Tóquio e especificaram seus nomes:

T("City", eq, "Tokyo") * T("Name", any)

Nota

Análogo à conjunção lógica (AND). Também pode ser escrito como operador and.

Diferença (\)

Constrói um segmento de usuários que pertencem a um dos segmentos descritos e não pertencem a outro.

Usuários que moram em Tóquio, mas não forneceram seus nomes, serão descritos da seguinte forma:

T("City", eq, "Tokyo") \ T("Name", any)

Nota

Equivalente à negação lógica (NOT). Também pode ser escrito como operador not.

Parênteses

Determinam a ordem das operações a serem realizadas com as condições em sua expressão de filtro.

Por exemplo, a seguinte expressão de filtro obterá primeiro um segmento de assinantes do 12345-67890 cuja idade é 18 e, em seguida, subtrairá todos os homens desse segmento:

( A("12345-67890") * T("Age", eq, 18) ) \ T("Gender", eq, "Male")

Operadores de condições de Tag

Para cada tipo de Tag, seus próprios operadores são aplicados.

Operadores de Tags de Inteiro

• eq - igual a um valor especificado
• noteq - não igual a um valor especificado
• lte - menor ou igual a um valor especificado
• gte - maior ou igual a um valor especificado
• in - qualquer um dos valores especificados
• notin - não igual a nenhum dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplo de sintaxe de Tags de Inteiro

T("int", eq, 42)

Operadores de Tags de String

• eq - igual a um valor especificado
• noteq - não igual a um valor especificado
• startswith - começa com um prefixo especificado
• endswith - termina com um sufixo especificado
• contains - contém uma substring especificada
• in - igual a qualquer um dos valores especificados
• notin - não igual a nenhum dos valores especificados
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplos de sintaxe de Tags de String

• T("str", eq, "kangaroo") - correspondência exata
• T("str", startswith, "kang") - começa com “kang”
• T("str", endswith, "roo") - termina com “roo”
• T("str", contains, "nga") - contém “nga” em qualquer lugar na string

Operadores de Tags de Lista

• in - dispositivos com qualquer um dos valores de tag especificados
• notin - nenhum dos valores de tag especificados associados ao dispositivo
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplo de sintaxe de Tags de Lista

T("list", notin, ["kangaroo", "raccoon"])

Operadores de Tags de Data

• eq - igual à data especificada
• noteq - não igual à data especificada
• lte - antes ou na data especificada
• gte - depois ou na data especificada
• in - igual a qualquer uma das datas especificadas
• notin - não igual a nenhuma das datas especificadas
• between - em um intervalo especificado
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag
• match - corresponde a um mês do ano e dia do mês especificados.

Exemplos do operador match

• AT("XXXXX-XXXXX", "Date tag", match month 4 day 1) - dispositivos que têm a “Date tag” definida para 1º de abril de qualquer ano.
• AT("XXXXX-XXXXX", "Date tag", match month "now" day 13) - dispositivos que têm a “Date tag” definida para o 13º dia do mês atual.
• AT("XXXXX-XXXXX", "Date tag", match month "now" day "now+2") - dispositivos que têm a “Date tag” definida para depois de amanhã. Caso de uso comum: saudações de aniversário.

Exemplos do operador Match para segmentos de aniversário e data comemorativa

Você pode segmentar usuários com base em datas recorrentes do calendário, como aniversários ou datas comemorativas. Nesses casos, apenas o mês e o dia são levados em consideração, enquanto o ano é ignorado.

• AT("XXXXX-XXXXX", "birthday", match month "now" day "now") Segmenta usuários cujo aniversário é hoje (mesmo dia e mês de hoje). Use isso para enviar saudações de aniversário ou ofertas especiais no dia do aniversário do usuário.

• AT("XXXXX-XXXXX", "birthday", match month "now" day "now+N") Segmenta usuários cujo aniversário é em N dias (mesmo mês e dia, N dias a partir de hoje). Use isso para preparar os usuários com antecedência, por exemplo, enviar mensagens de contagem regressiva ou lembretes de eventos futuros.

• AT("XXXXX-XXXXX", "birthday", match month "now" day "now-N") Segmenta usuários cujo aniversário foi há N dias. Use isso para mensagens de aniversário atrasadas ou acompanhamentos, como solicitações de feedback.

• AT("XXXXX-XXXXX", "birthday", match month "now" day N) Segmenta usuários cujo aniversário é no N-ésimo dia do mês atual, independentemente do ano. Use isso ao planejar campanhas mensais fixas vinculadas a datas específicas (por exemplo, recompensas de fidelidade mensais no dia 10).

• daysago eq - igual a um número especificado de dias antes do dia atual
• daysago noteq - não igual a um número especificado de dias antes do dia atual
• daysago lte - menor ou igual a um número especificado de dias antes do dia atual
• daysago gte - maior ou igual a um número especificado de dias antes do dia atual
• daysago between - entre os números de dias especificados

Exemplos do operador daysago

• T("Date tag", daysago, eq, 0) - o dia atual das 00:00 até o momento atual
• T("Date tag", daysago, eq, 1) - das 00:00 do dia anterior até as 00:00 do dia atual
• T("Date tag", daysago, gte, 1) - todo o tempo até as 00:00 do dia atual
• T("Date tag", daysago, lte, 7) - das 00:00 do dia 6 dias atrás até o momento atual
• T("Date tag", daysago, between, [2,7]) - de 7 a 2 dias atrás.

• minutesago lte - menor ou igual a um número especificado de minutos antes do momento atual
• minutesago gte - maior ou igual a um número especificado de minutos antes do momento atual

Exemplos do operador minutesago

• T("Date tag", minutesago, lte, 30) - os últimos 30 minutos;
• T("Date tag", minutesago, gte, 60) - 60 ou mais minutos atrás;
• T("Date tag", minutesago, lte, 1) - no último minuto.

• daysahead - em N a M dias a partir do dia atual (UTC), inclusivo em ambas as extremidades

Exemplos do operador daysahead

daysahead usa um intervalo [from, to] (dias a partir da meia-noite UTC de hoje, ambas as extremidades inclusivas). Ao contrário de daysago, ele não tem um suboperador — apenas a forma de intervalo.

• T("Date tag", daysahead, [0, 0]) - o dia atual das 00:00 às 23:59:59
• T("Date tag", daysahead, [1, 1]) - o dia seguinte das 00:00 às 23:59:59
• T("Date tag", daysahead, [2, 5]) - qualquer momento desde o início de 2 dias a partir de agora até o final de 5 dias a partir de agora

Exemplo do operador de data

• T("Date tag", eq "2022-12-05 00:00:00")

Operadores de Tags Booleanas

• eq - igual a um valor especificado
• noteq - não igual a um valor especificado
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplo de sintaxe de Tags Booleanas

T("bool", eq, true)

Operadores de Tags de Preço

• eq - igual a um valor especificado
• noteq - não igual a um valor especificado
• lte - menor ou igual a um valor especificado
• gte - maior ou igual a um valor especificado
• in - igual a qualquer um dos valores especificados
• notin - não igual a nenhum dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplo de sintaxe de Tags de Preço

T("price", between, ["4.2", "6.9"])

Operadores de Tags de Versão

• eq - igual a um valor especificado
• noteq - não igual a um valor especificado
• lte - menor ou igual a um valor especificado
• gte - maior ou igual a um valor especificado
• in - igual a qualquer um dos valores especificados
• notin - não igual a nenhum dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com quaisquer valores definidos para a tag
• notset - dispositivos sem valor definido para a tag

Exemplo de sintaxe de Tags de Versão

T("version", lte, "4.2")

Operadores de condições de Evento

Nota

Por favor, lembre-se que as condições de evento são específicas do aplicativo, então o código do aplicativo deve ser especificado em suas expressões de filtro junto com o nome do evento.

Contagem de eventos

• count gte - dispositivos que acionaram o evento mais ou exatamente n vezes
• count lte - dispositivos que acionaram o evento menos ou exatamente n vezes
• count eq - dispositivos que acionaram o evento exatamente n vezes
• count noteq - dispositivos que acionaram o evento qualquer número de vezes, mas não igual a n

Exemplo de sintaxe de contagem de eventos

Event("11111-11111", "Level reached", count gte 10) // 11111-11111 é um código de aplicativo

Data do evento

• date gte - dispositivos que acionaram o evento depois ou exatamente na data especificada
• date lte - dispositivos que acionaram o evento antes ou exatamente na data especificada
• date eq - dispositivos que acionaram o evento exatamente na data especificada
• date noteq - dispositivos que acionaram o evento a qualquer momento, mas não na data especificada
• date in - dispositivos que acionaram o evento em qualquer uma das datas especificadas
• date notin - dispositivos que acionaram o evento a qualquer momento, mas não em nenhuma das datas especificadas
• date between - dispositivos que acionaram o evento dentro de um período especificado
• date daysago eq - a data de acionamento do evento é igual a um número especificado de dias antes do dia atual
• date daysago noteq - a data de acionamento do evento não é igual a um número especificado de dias antes do dia atual
• date daysago lte - a data de acionamento do evento é menor ou igual a um número especificado de dias antes do dia atual
• date daysago gte - a data de acionamento do evento é maior ou igual a um número especificado de dias antes do dia atual
• date daysago between - a data de acionamento do evento está entre os números de dias especificados
• date daysahead - a data de acionamento do evento está em um número especificado de dias a partir do dia atual (o intervalo é inclusivo em ambas as extremidades, veja Operadores de Tags de Data acima para a semântica completa)
• date minutesago lte - a data de acionamento do evento é menor ou igual a um número especificado de minutos antes do momento atual
• date minutesago gte - a data de acionamento do evento é maior ou igual a um número especificado de minutos antes do momento atual

Exemplos de sintaxe de data de evento

• Event("11111-11111", "Level reached", date gte "2022-01-01 01:02:03")
• Event("11111-11111", "Level reached", date in ["2022-01-01 01:02:03", "2022-01-01 02:03:04"])
• Event("11111-11111", "Level reached", date between "2022-01-01 01:02:03" "2022-01-01 02:03:04")
• Event("11111-11111", "Level reached", date daysahead 0 7) - eventos com data de acionamento nos próximos 7 dias
• Event("11111-11111", "Level reached", date minutesago lte 30) - eventos nos últimos 30 minutos
• Event("11111-11111", "Level reached", date minutesago gte 60) - eventos há 60+ minutos

Plataformas de eventos

Filtre eventos pela plataforma onde foram acionados.

• platforms - lista de plataformas (ex: [“ios”, “android”])

Exemplo de sintaxe de plataformas de eventos

Event("11111-11111", "Level reached", platforms ["android", "ios"], count gte 5)

Atributos de eventos

As condições de evento podem filtrar com base nos valores dos atributos do evento. Os atributos suportam vários tipos de dados com seus operadores correspondentes.

Atributos de Evento de Inteiro

• attribute “name” eq - atributo igual a um valor especificado
• attribute “name” noteq - atributo não igual a um valor especificado
• attribute “name” gte - atributo maior ou igual a um valor especificado
• attribute “name” lte - atributo menor ou igual a um valor especificado
• attribute “name” between - atributo em um intervalo especificado
• attribute “name” in - atributo igual a qualquer um dos valores especificados
• attribute “name” notin - atributo não igual a nenhum dos valores especificados
• attribute “name” any - qualquer valor definido para o atributo
• attribute “name” notset - nenhum valor definido para o atributo

Exemplos de sintaxe de atributo de inteiro

• Event("11111-11111", "Purchase", attribute "amount" eq 42)
• Event("11111-11111", "Purchase", attribute "amount" between 10 100)
• Event("11111-11111", "Purchase", attribute "amount" in [10, 20, 30])

Atributos de Evento de String

• attribute “name” eq - atributo igual a um valor especificado
• attribute “name” noteq - atributo não igual a um valor especificado
• attribute “name” startswith - atributo começa com um prefixo especificado
• attribute “name” endswith - atributo termina com um sufixo especificado
• attribute “name” contains - atributo contém uma substring especificada
• attribute “name” in - atributo igual a qualquer um dos valores especificados
• attribute “name” notin - atributo não igual a nenhum dos valores especificados
• attribute “name” any - qualquer valor definido para o atributo
• attribute “name” notset - nenhum valor definido para o atributo

Exemplos de sintaxe de atributo de string

• Event("11111-11111", "Page View", attribute "url" startswith "https://example.com")
• Event("11111-11111", "Page View", attribute "url" endswith ".html")
• Event("11111-11111", "Page View", attribute "url" contains "/products/")
• Event("11111-11111", "Button Click", attribute "button_name" in ["submit", "cancel"])

Atributos de Evento Booleanos

• attribute “name” eq - atributo igual a true ou false
• attribute “name” noteq - atributo não igual a true ou false

Exemplo de sintaxe de atributo booleano

Event("11111-11111", "Feature Toggle", attribute "enabled" eq true)

Atributos de Evento de Data

• attribute “name” eq - atributo igual a uma data especificada
• attribute “name” noteq - atributo não igual a uma data especificada
• attribute “name” gte - atributo depois ou em uma data especificada
• attribute “name” lte - atributo antes ou em uma data especificada
• attribute “name” between - atributo dentro de um intervalo de datas especificado
• attribute “name” in - atributo igual a qualquer uma das datas especificadas
• attribute “name” notin - atributo não igual a nenhuma das datas especificadas
• attribute “name” daysago eq/noteq/gte/lte/between - atributo relativo a dias atrás
• attribute “name” daysahead from to - atributo em um intervalo especificado de dias a partir do dia atual (o intervalo é inclusivo em ambas as extremidades, veja Operadores de Tags de Data acima para a semântica completa)
• attribute “name” minutesago gte/lte - atributo relativo a minutos atrás
• attribute “name” any - qualquer valor definido para o atributo
• attribute “name” notset - nenhum valor definido para o atributo

Exemplos de sintaxe de atributo de data

• Event("11111-11111", "Subscription", attribute "start_date" eq "2022-01-01 01:02:03")
• Event("11111-11111", "Subscription", attribute "start_date" between "2022-01-01 00:00:00" "2022-12-31 23:59:59")
• Event("11111-11111", "Subscription", attribute "start_date" daysago lte 30) - nos últimos 30 dias
• Event("11111-11111", "Subscription", attribute "renewal_at" daysahead 0 30) - renovações nos próximos 30 dias
• Event("11111-11111", "Subscription", attribute "start_date" minutesago gte 60) - há 60+ minutos

Atributos de Evento de Preço

• attribute “name” eq - atributo igual a um valor de preço especificado
• attribute “name” noteq - atributo não igual a um valor de preço especificado
• attribute “name” gte - atributo maior ou igual a um preço especificado
• attribute “name” lte - atributo menor ou igual a um preço especificado
• attribute “name” between - atributo em um intervalo de preços especificado
• attribute “name” in - atributo igual a qualquer um dos preços especificados
• attribute “name” notin - atributo não igual a nenhum dos preços especificados
• attribute “name” any - qualquer valor definido para o atributo
• attribute “name” notset - nenhum valor definido para o atributo

Exemplo de sintaxe de atributo de preço

Event("11111-11111", "Purchase", attribute "total_price" between 10.00 50.00)

Atributos de Evento de Lista

• attribute “name” in - atributo contém qualquer um dos valores especificados
• attribute “name” notin - atributo não contém nenhum dos valores especificados
• attribute “name” any - qualquer valor definido para o atributo
• attribute “name” notset - nenhum valor definido para o atributo

Exemplo de sintaxe de atributo de lista

Event("11111-11111", "Cart Update", attribute "product_ids" in ["prod-123", "prod-456"])

Tipos de condição adicionais

Condição Geo

Segmente dispositivos com base na localização geográfica dentro de um raio especificado.

Sintaxe: Geo("<app-code>", <latitude>, <longitude>, <range-in-km>)

Exemplo de sintaxe Geo

Geo("11111-11111", 53.2734, -7.77832031, 100.05) - dispositivos dentro de 100,05 km das coordenadas

Condição BTTS

Segmente dispositivos pelo melhor horário para enviar notificações (hora do dia, 0-23).

Operadores:

• any - qualquer valor de melhor horário para enviar definido
• eq - correspondência exata da hora
• noteq - não igual à hora
• gte - hora maior ou igual a
• lte - hora menor ou igual a

Exemplos de sintaxe BTTS

• BTTS("11111-11111", eq 10) - dispositivos com melhor horário às 10:00
• BTTS("11111-11111", gte 18) - dispositivos com melhor horário a partir das 18:00
• BTTS("11111-11111", any) - dispositivos com qualquer valor de melhor horário

Condição Updated

Filtre dispositivos pelo seu último carimbo de data/hora de atualização.

Operadores:

• gte - atualizado depois ou na data especificada
• lte - atualizado antes ou na data especificada
• between - atualizado dentro do intervalo de datas

Exemplos de sintaxe Updated

• Updated("11111-11111", gte "2022-01-01 00:00:00") - dispositivos atualizados após 1 de janeiro de 2022
• Updated("11111-11111", lte "2022-12-31 23:59:59") - dispositivos atualizados antes de 31 de dezembro de 2022
• Updated("11111-11111", between "2022-01-01 00:00:00" "2022-12-31 23:59:59") - dispositivos atualizados em 2022

Condição Segment

Referencie outro filtro/segmento por seu código.

Exemplo de sintaxe de Segment

Segment("11111-11111", "22222-22222") - referencia o filtro com o código “22222-22222”

Flags de presença de dispositivo da condição Application

As condições de Application suportam flags adicionais para controlar a filtragem de dispositivos e tokens:

• with_tokens - dispositivos com tokens de notificação push
• without_tokens - dispositivos sem tokens de notificação push
• with_devices - usuários com dispositivos registrados
• without_devices - usuários/perfis sem dispositivos registrados

Exemplos de sintaxe de flags de Application

• A("11111-11111", ["ios", "android"], [with_tokens]) - dispositivos com tokens de push
• A("11111-11111", ["ios", "android"], [without_tokens]) - dispositivos sem tokens de push
• A("11111-11111", [], [with_devices]) - todos os dispositivos com registros de dispositivo
• A("11111-11111", ["ios", "android"], [without_tokens, with_devices]) - dispositivos sem tokens, mas com registros de dispositivo

Exemplos de expressão de filtro

Nota

Ao escrever consultas JSON, certifique-se de escapar aspas (") e barras invertidas (\) com uma barra invertida (\). Para um exemplo de solicitação, veja /exportSegment.

Exemplos básicos

1. Dispositivos iOS e Android com o aplicativo instalado e com tokens de push:

A("11111-11111", ["ios","android"], [with_tokens])

2. Dispositivos iOS e Android com o aplicativo instalado, mas sem tokens de push:

A("11111-11111", ["ios","android"], [without_tokens])

3. Dispositivos iOS e Android com o aplicativo instalado, tenham eles tokens de push ou não:

A("11111-11111", ["ios","android"], [with_tokens, without_tokens])

4. Todos os assinantes do aplicativo que compraram algo no aplicativo:

AT("11111-11111", "In-App Purchase", gte, 1)

Exemplos avançados

5. Usuários em Tóquio que abriram o aplicativo nos últimos 7 dias:

T("City", eq, "Tokyo") * Event("11111-11111", "App Open", date daysago lte 7)

6. Usuários que fizeram uma compra acima de $50 nos últimos 30 dias:

Event("11111-11111", "Purchase", attribute "total_price" gte 50.00, date daysago lte 30)

7. Usuários cujos nomes começam com “J” ou terminam com “e”:

T("Name", startswith, "J") + T("Name", endswith, "e")

8. Usuários ativos de iOS a 100 km de Nova York que não compraram recentemente:

A("11111-11111", ["ios"], [with_tokens]) * Geo("11111-11111", 40.7128, -74.0060, 100) \ Event("11111-11111", "Purchase", date daysago lte 30)

9. Usuários com melhor horário para enviar entre 9h e 17h:

BTTS("11111-11111", gte 9) * BTTS("11111-11111", lte 17)

10. Usuários que acionaram um evento específico no Android ou iOS na última hora:

Event("11111-11111", "Button Click", platforms ["android", "ios"], date minutesago lte 60)

11. Dispositivos atualizados nos últimos 3 meses com a versão do aplicativo 4.2 ou superior:

Updated("11111-11111", gte "2024-07-01 00:00:00") * AT("11111-11111", "App Version", gte, "4.2")