Uma regra é um fato, um valor e um teto
Dois tipos de gatilho
event é um fato que a plataforma já publica sobre uma pessoa: verificou o
e-mail, entrou num time, saiu da lista de espera. Não há nada para instrumentar.
A lista completa vem na própria leitura das regras, em event_types.
product_event é um nome que o seu produto manda pelo
track(). O vocabulário é seu, então nada aqui pode
recusar um nome por não existir — o que o painel faz é dizer se este ambiente já
viu aquele nome alguma vez, que é a metade honesta de uma verificação que não
pode reprovar.
Não existe gatilho de “direito”. Um ponto é um acontecimento; um direito é um
estado. Pagar por um estado exigiria um relógio perguntando “ainda tem?” e um
estorno quando deixasse de ter — e a resposta pertence a um time, do qual uma
pessoa pode fazer parte de vários. Um saldo cujo valor depende de qual aba
resolveu a pergunta não é um saldo.
O teto não tem padrão, e é de propósito
award_limit é obrigatório:
A primeira regra que alguém aponta para um evento frequente sem teto é um laço
sem fim com uma tabela no fim dele. As janelas são corridas e não de
calendário: ninguém ganha uma cota nova numa meia-noite que a gente escolheu por
ele.
Na listagem, cada regra volta com
awards e earners. Muitas concessões para
poucas pessoas é o formato do erro que este módulo tem: um teto deixado em
unlimited num nome que o produto manda em toda página.
O que não muda depois
key, kind e event_type são congelados. As linhas que a regra já escreveu
dizem “você ganhou isto por X”, então reapontá-la reescreveria o histórico de
todo mundo sem tocar em uma linha sequer. Aposente a regra e crie outra: as
linhas antigas guardam o nome que a regra tinha na hora.
Repreçar é permitido e não é retroativo. Mudar de 10 para 5 muda o que a
próxima concessão vale, e nada do que já aconteceu.
Métricas: o que você conta além de pontos
Enquanto a única unidade era o ponto, “ouro é 4 cursos” só dava para escrever como “uma regra que paga 1 ponto por curso, e ouro são 4 pontos” — e aí a unidade morria na porta: no instante em que o fato virava linha do extrato, ele tinha deixado de ser um curso. Uma métrica devolve a unidade.metric_id, points é quanto daquela métrica vale uma ocorrência: 1
curso, 1 e-mail. O saldo não se mexe, e uma conquista points_total não é
liberada por isso — um crédito de métrica não moveu saldo nenhum.
Criar uma métrica não faz nada sozinha. Sem uma regra creditando, ela fica em
zero para todo mundo, e todo degrau que a pede fica vazio junto — é por isso que
a listagem devolve lines e holders, que são o par que denuncia isso antes de
alguém abrir um chamado dizendo que o programa não funciona. A ordem que
funciona é métrica, depois regra, depois nível.
Níveis são uma função do que a pessoa tem
Um degrau é um conjunto de condições, e todas precisam valer:
O último é o único que pode deixar de valer: sair do público derruba o nível.
Se a intenção era “quem chegou ao Pro” e não “quem está no Pro”, use uma medalha
de segmento — ela é escrita para sempre no instante em que é ganha.
O nível não é guardado em ninguém: ele é derivado a cada leitura como o degrau de
maior
rank cujas condições todas valem. É o que impede que ele discorde do
extrato, das contas e das medalhas que o descrevem.
A ordem virou um campo
O limite era a própria ordem enquanto um degrau era um número só. Deixou de poder ser: nenhuma aritmética compara “400 pontos e 4 cursos” com “400 pontos e 10 cursos”. Orank é a única coisa que ordena a escada, e é único por
ambiente. Omitir rank na criação põe o degrau acima do último — que é o que
criar um nível quase sempre é.
Dois degraus no mesmo saldo agora são permitidos, e é exatamente para isso
que isto existe: ouro pode ser 400 pontos e 4 cursos enquanto platina é 400
pontos e 10.
Coisas que vale ler antes de precisar delas
- Um degrau sem condições é alcançado por NINGUÉM, e não por todo mundo. A leitura contrária promoveria o ambiente inteiro no instante em que alguém cria um nível e sai para almoçar.
- Uma linha negativa derruba o nível junto com o saldo, na hora e sem
anúncio — e o mesmo vale para sair de um público que um degrau pede. Não
existe
level_lost: rebaixar alguém não é um comunicado que produto nenhum quer fazer em seu nome. - O anúncio acontece uma vez só. Quem alcança três degraus de uma vez — uma
correção grande, uma fusão de cadastros, uma medalha que era a última condição
de dois níveis — recebe um
points.level_reached, o do degrau mais alto. Três fatos no mesmo segundo seriam três e-mails sobre o mesmo momento. - Editar as condições move quem está no nível na hora, sem linha nenhuma no extrato. É a diferença entre um nível e uma regra: uma regra descreve o que aconteceu, e um nível descreve o que é verdade agora.
Conquistas
Três formatos, cada um satisfeito por uma máquina diferente:
O terceiro é o mais barato de acertar, porque reaproveita o motor de públicos que
você já usa — e a única diferença entre uma medalha e um segmento é que a
medalha não sai. Quem foi trialista de enterprise em março continua com a
medalha em junho; recalcular pela definição a tiraria de volta.
hidden esconde a medalha de quem ainda não a tem. É metade da graça do
mecanismo por um booleano — e funciona porque a condição nunca vai para o
navegador: a API manda um nome, um desenho e se é sua. Dizer “libera com 40
convites” é entregar a regra para ser farmada.
A condição também é congelada. Quem já tem a medalha ganhou a antiga, e editar o
que ela quer dizer mudaria o que cada liberação existente afirma.
Apagar uma regra que uma conquista
event_count conta é recusado, e o erro diz
quantas conquistas estão no caminho. Uma medalha cuja regra não existe mais é uma
medalha na estante que ninguém consegue mais tirar.Mostrando para a pessoa
<PointsPill /> é o gêmeo do <OnboardingLauncher /> — mesma pílula, mesmo
anel — para os lugares onde um cartão não cabe. Ele não abre nada: não existe
painel flutuante de pontos, então onClick serve para o produto que tem a
própria página. Num produto sem gamification configurada ele não desenha nada.
Ou pelo cliente, se você desenha a sua própria tela:
level é null quando nenhum degrau foi alcançado — inclusive no caso comum
de um produto sem níveis nenhum. Desenhe o nulo: um zero seria uma posição que
ninguém configurou.
points_to_next continua sendo só a distância em pontos, e é zero quando o
próximo degrau não pede pontos. Numa escada com métricas, desenhe a barra a
partir de next_level.requirements: “faltam 60 pontos” numa condição que também
quer quatro cursos é uma barra que enche e não promove ninguém.
As condições de um nível viajam para o navegador e as de uma medalha
não, na mesma resposta, e é o mesmo princípio duas vezes. Uma medalha é uma
surpresa que o produto tem direito de guardar; um degrau é uma meta que o
produto está pedindo para a pessoa alcançar. A única coisa retida é o nome
de um público — esse é o seu texto interno sobre os seus usuários, e nunca foi
escrito para eles lerem.
Não existe escrita nesta superfície
Nenhum endpoint do plano do cliente mexe num saldo, e não vai existir. É a mesma regra da checklist, pelo mesmo motivo: no instante em que uma página consegue pedir pontos, a aba de rede daquela página vira o jogo.Concedendo pontos pelo seu back-end
A exceção, e ela mora na superfície de máquina — um programa seu, não uma página que você publica:request_key é obrigatório — diferente da chave opcional do
/v1/usage. Uma concessão repetida sem chave é um
segundo presente, e quem mais quer este endpoint é um script que alguém roda duas
vezes. A repetição responde 200 com duplicate: true e o saldo como está: o
estado que você pediu é verdade, então um erro seria uma repetição para tratar
diante de um resultado correto.
A linha entra com source: "manual", que é a coluna para agrupar quando um saldo
parecer impossível. Um contato anônimo é recusado: saldo em visitante pertence a
um carregamento de página, não a uma pessoa.
Com metric, o mesmo endpoint credita uma conta em vez do saldo — a porta
para o que aconteceu fora do seu produto:
request_key obrigatória, mesma linha no mesmo extrato. O balance da
resposta passa a ser a conta daquela métrica, e metric ao lado dele diz qual
foi movida.
Os fatos que saem daqui
Três, e todos entregues aos seus webhooks:points.awarded é o fato mais frequente do catálogo por construção — ele dispara
por linha. O que o limita é o award_limit da regra, que é exatamente o motivo de
ele não ter padrão.
Uma regra não pode escutar esses três. Pagar por ser pago é um laço que roda
na velocidade da fila, e a API recusa a regra na hora de criá-la.