Documentação do Mappings for Wealthbox

Introdução

O Mappings for Wealthbox envia cada submissão do Gravity Forms diretamente para o Wealthbox CRM como contacto, sem Zapier, sem exportar CSV e sem copiar e colar. Escolhe um formulário, define para que campo do Wealthbox vai cada campo do formulário e publica. A partir daí, cada submissão cria o contacto no Wealthbox em segundos.

Foi feito para consultores financeiros, RIAs e as agências que gerem os seus sites: empresas que recebem contactos no WordPress e trabalham no Wealthbox. O plugin tem duas partes:

• Mappings for Wealthbox (grátis) cria contactos novos a partir de qualquer formulário do Gravity Forms, com os campos padrão de contacto do Wealthbox.
• Mappings for Wealthbox Pro ($49, pagamento único, um site) é um complemento instalado ao lado do plugin grátis. Acrescenta campos personalizados, atualização de contactos existentes, registos de sincronização e suporte para GP Nested Forms.

Veja a comparação Grátis vs Pro para a lista completa.

Requisitos e instalação

Instalar o plugin grátis

1. No WordPress, vá a Plugins › Add New › Upload Plugin.
2. Carregue mappings-for-wealthbox.zip e clique em Install Now.
3. Clique em Activate. Aparece um novo menu Wealthbox na barra lateral.

Instalar o Pro

1. Confirme que o plugin grátis está instalado e ativo. O Pro é um complemento e não funciona sem ele.
2. Carregue mappings-for-wealthbox-pro.zip da mesma forma e ative-o.
3. Ao ativar, o Pro cria duas tabelas na base de dados, para o índice de contactos e os registos. Aparece o item Logs no menu Wealthbox.

Se o plugin grátis não estiver ativo, o Pro mostra um aviso a pedir que o instale e ative, e não faz mais nada.

Ligar ao Wealthbox

O plugin comunica com o Wealthbox através de um token de acesso, guardado em Wealthbox › Settings. A página tem dois separadores: General e Connection & Cache.

Obter o token de acesso

1. Entre no Wealthbox e abra Settings › API Access.
2. Crie um token e copie-o.

Separador General

Cole o token, confirme o Base URL e clique em Save Changes.

Separador Connection & Cache

• Test connection envia um pedido ao Wealthbox. Vê uma mensagem de sucesso quando funciona, "Authentication failed (HTTP 401 ou 403)" se o token estiver errado, ou o erro HTTP noutros casos. Guarde o token antes de testar.
• Custom field cache (Pro) mostra quantos campos personalizados estão em cache. Atualiza sozinha a cada 3 horas. Clique em Clear cache & re-fetch fields depois de criar ou renomear um campo no Wealthbox.

Os pedidos expiram ao fim de 20 segundos.

Criar uma associação

Uma associação (mapping) liga um formulário do Gravity Forms ao Wealthbox. Fica em Wealthbox › Mappings e só funciona depois de publicada.

1. Vá a Wealthbox › Mappings › Add New.
2. Dê-lhe um título fácil de reconhecer, por exemplo "Formulário de contacto".
3. Escolha o formulário em Gravity Form. A tabela de campos carrega de imediato.
4. (Pro) Escolha a Action e, nos modos de atualização, o campo Match using.
5. Em cada linha, escolha o campo do Wealthbox na coluna da direita. Deixe em Not mapped para ignorar. As listas têm pesquisa.
6. Clique em Publish.

A tabela de campos

• A coluna da esquerda lista cada campo do formulário com a sua chave do Gravity Forms, por exemplo 1.3.
• Campos com várias partes (Nome, Morada) aparecem uma vez com o valor completo e depois uma vez por parte, como "Name, First" ou "Address, City".
• Caixas de seleção e Multi Select aparecem uma vez. Todas as escolhas são enviadas juntas.
• Quebras de página, secções, blocos HTML e CAPTCHA ficam de fora.
• Os campos filhos do Nested Forms têm a etiqueta nested (Pro).

Campos ocultos

Campos ocultos do Gravity Forms, como ID de utilizador, UTM ou valores de tracking, ficam escondidos por defeito. Marque Show hidden fields para os associar.

Duplicar uma associação

Passe o rato sobre uma associação na lista e clique em Duplicate. Fica com uma cópia em rascunho com o mesmo formulário, ação, correspondência e campos.

Uma associação por formulário

Se houver mais do que uma associação publicada para o mesmo formulário, só a publicada mais recentemente funciona. Mantenha as outras em rascunho. A lista tem a coluna Gravity Form, que pode ordenar.

Campos do Wealthbox e formatação de valores

O plugin grátis associa a nove campos padrão de contacto do Wealthbox. O Pro acrescenta todos os seus campos personalizados.

Se não houver nome próprio nem apelido, o contacto fica com o nome Web Lead, porque o Wealthbox exige um nome.

Como os valores são enviados

Se associar apenas uma parte de um campo (por exemplo só a caixa de consentimento 5.1), é enviado o valor bruto dessa parte.

Pro: ações de sincronização e correspondência

O Pro permite que cada associação decida o que acontece quando alguém que já está no Wealthbox volta a enviar o formulário. Escolha em Action no ecrã da associação.

O plugin grátis usa sempre Create contact only. Se desativar o Pro, as associações com ações de atualização são ignoradas, não passam a criar contactos, até o Pro voltar a estar ativo.

Match using

• O campo do formulário com o valor, por exemplo o seu campo de email.
• O tipo, Email ou Phone. Os emails ficam sem espaços e em minúsculas. Os telefones ficam só com os dígitos, por isso "(555) 010-2233" e "5550102233" correspondem.

Como funciona a correspondência

Sempre que o plugin cria ou atualiza um contacto, guarda uma impressão SHA-256 do email e do telefone, com o ID do contacto no Wealthbox, numa tabela própria. O email e o telefone reais nunca ficam lá guardados. Na submissão seguinte, calcula a impressão do valor e procura-a: uma pesquisa na base de dados, sem chamada à API.

O índice só conhece contactos que o próprio plugin criou ou atualizou. Um contacto que já estava no Wealthbox antes de instalar o Pro ainda não é encontrado, por isso Create and update cria um segundo registo para essa pessoa. A correspondência com contactos existentes está prevista numa atualização.

Pro: campos personalizados

Com o Pro ativo, todos os campos personalizados de contacto do Wealthbox aparecem na lista em Custom fields, abaixo dos campos padrão.

Associação automática

Ao carregar um formulário, o Pro pré-seleciona um campo personalizado para cada campo cujo rótulo coincida com o nome do campo personalizado, ignorando maiúsculas e espaços extra. Confirme as sugestões antes de publicar. Uma escolha guardada tem sempre prioridade.

Nome, email e telefone em campos personalizados

Se associar um campo Email, Phone ou Name do Gravity Forms a um campo personalizado, o Pro preenche também o campo padrão correspondente, para o contacto ter sempre nome, email e telefone:

• Campo Email: também é adicionado como email do contacto
• Campo Phone: também é adicionado como telefone do contacto
• Name, First (x.3): também fica como nome próprio
• Name, Last (x.6): também fica como apelido

A cache

As definições dos campos personalizados são obtidas 100 de cada vez para cada tipo de documento escolhido nas definições, até 5.000 campos, e ficam em cache durante 3 horas, para o ecrã nunca esperar pela API. Uma cache vazia volta a encher no carregamento seguinte. Por agora, só os campos de Contact aparecem na lista.

Pro: GP Nested Forms

O Pro permite associar os campos dentro de um campo Gravity Perks Nested Forms, por exemplo várias moradas, dependentes ou contas num só formulário. Cada campo filho aparece na sua linha, como "Campo pai → Campo filho", com uma chave como nested:12:3 (campo pai 12, campo filho 3).

Na submissão, cada entrada filha passa a ser uma linha numerada, com o nome do campo filho:

Morada-1: Rua Alta 12, Porto, 4000-123, Portugal
Morada-2: Rua Nova 8, Gaia, 4400-001, Portugal

• Associe o campo filho completo para receber todas as partes separadas por vírgulas, como acima.
• Associe uma parte (nested:12:3.3) para receber só essa parte em cada linha.
• Envie linhas aninhadas para um campo personalizado de texto ou para Background information, porque o resultado tem várias linhas.
• As linhas aninhadas não podem ser o campo Match using.

Pro: registos de sincronização

Cada submissão num formulário associado escreve uma linha em Wealthbox › Logs, para ver exatamente o que foi enviado e o que o Wealthbox respondeu.

Ordene por data, formulário, entrada, estado ou código HTTP, filtre por datas e defina linhas por página em Screen Options. Os registos contêm dados dos formulários, por isso trate-os como dados pessoais. Ficam guardados até desinstalar o Pro; a limpeza automática está prevista numa atualização.

Referência para programadores

O plugin grátis é um pequeno motor com hooks. O Pro foi feito inteiramente com esses hooks, por isso pode estendê-lo da mesma forma.

Hooks do plugin grátis

Hooks do Pro

Exemplo: etiquetar cada contacto do site

add_filter( 'wbm_contact_payload', function ( $payload, $entry, $form ) {
    $payload['tags'] = [ 'Website lead' ];
    return $payload;
}, 10, 3 );

Onde ficam os dados

O código usa o namespace MappingsForWealthbox (Pro: MappingsForWealthbox\Pro). A interface Wealthbox_Resource permite acrescentar outros tipos de registo do Wealthbox como novas classes, sem mexer no motor de sincronização.

Desativar e desinstalar

Desativar nunca apaga nada. Apagar um plugin remove só os dados desse plugin, e nada no Wealthbox é apagado.

Resolução de problemas e perguntas

Limitações conhecidas

• Os modos de atualização só encontram contactos que o plugin criou ou atualizou.
• Os registos não são limpos automaticamente.
• Só é usada uma associação publicada por formulário.
• Por agora, só são suportados contactos do Wealthbox.

Tem uma dúvida que a documentação não responde? Fale comigo.

Versões e créditos

Criado por Samama Tahir. Licença GPL v2 ou posterior. Wealthbox é uma marca do respetivo proprietário e Gravity Forms é uma marca da Rocketgenius. Este plugin é independente e não tem ligação a nenhuma delas.