Linguagem de segmentação

A Pushwoosh oferece um poderoso motor de segmentação para construir Segmentos granulares com base nos valores das Tags. 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 dos valores de Tag.

Por exemplo, digamos que uma usuária chamada Jane mora em Tóquio e sua idade é 28 anos. 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

Uma 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-specific tag) – aplicado em combinação com os códigos de aplicativo para tags que são específicas do aplicativo. 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 timestamp de atualização;
• Segment – referencia outro filtro/segmento por seu código;
• Static (ou S) – referencia um segmento estático pré-definido;

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 (OU). 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 (E). 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 (NÃO). 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 dos assinantes de 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 - diferente de 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 - diferente de qualquer um dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com qualquer valor definido 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 - diferente de 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 - diferente de qualquer um dos valores especificados
• any - dispositivos com qualquer valor definido 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 da 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 qualquer valor definido 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 - diferente da data especificada
• lte - antes ou na data especificada
• gte - depois ou na data especificada
• in - igual a qualquer uma das datas especificadas
• notin - diferente de qualquer uma das datas especificadas
• between - em um intervalo especificado
• any - dispositivos com qualquer valor definido 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 conta, 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 - diferente de 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.

Exemplo do operador date

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

Operadores de Tags Booleanas

• eq - igual a um valor especificado
• noteq - diferente de um valor especificado
• any - dispositivos com qualquer valor definido 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 - diferente de 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 - diferente de qualquer um dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com qualquer valor definido 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 - diferente de 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 - diferente de qualquer um dos valores especificados
• between - em um intervalo especificado
• any - dispositivos com qualquer valor definido 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, tenha em mente 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 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 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 diferente de 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 diferente de qualquer um 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 diferente de 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 diferente de qualquer um 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 verdadeiro ou falso
• attribute “name” noteq - atributo diferente de verdadeiro ou falso

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 diferente de 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 diferente de qualquer uma das datas especificadas
• attribute “name” daysago eq/noteq/gte/lte/between - atributo relativo a dias atrás
• 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 "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 diferente de 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 diferente de qualquer um 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 - diferente da 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 timestamp de atualização.

Operadores:

• gte - atualizado após 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 pelo seu código.

Exemplo de sintaxe de Segment

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

Condição Static

Referencie um segmento estático pré-definido. Pode usar Static ou a abreviação S.

Exemplo de sintaxe de Static

• Static("11111-11111", "segment-name")
• S("11111-11111", "segment-name") - versão abreviada

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 as aspas (") e as barras invertidas (\) com uma barra invertida (\). Para um exemplo de solicitação, consulte /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, quer tenham 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)

Nota

Por favor, leve em conta que as tags específicas do aplicativo são designadas como AT em vez de T, e o código do aplicativo deve ser especificado.

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")