Documentação técnica sobre o funcionamento e implementação da integração com a Jeenga via Java Script, API Web Server e SDK Mobile.

Push Web

Usando o Push Web você vai poder engajar os seus contatos que não interagem com você nos e-mails.

 

Para instalar o Push Web os passos são:

1 – A página que irá solicitar a permissão do usuário para que o site possa enviar o Push precisa estar em SSL, podendo ser a home, uma página específica ou todo o site.

Como o Google recentemente divulgou que os sites que estiverem em SSL serão “melhor ranqueados” então, também é uma ótima oportunidade para fazer este trabalho. Para ver como funciona esta permissão solicitada ao usuário, entre na home da Jeenga (https://www.jeenga.com/) e se você já não tiver aceitado ele vai te pedir.

2 – Além do SSL você precisa instalar 2 arquivos na raiz do seu site, este é o segundo pré-requisito do Google e vai garantir que o site é mesmo seu e que está habilitado para solicitar e enviar push.

Com as listas criadas você poderá enviar um mensagens de Push para cada lista ou para todo os seus contatos, baseado em quem visitou uma página e não uma outra, por perfil de usuário ou simplesmente enviar para todo mundo divulgando um novo conteúdo, e-Book, etc.

O Facebook habilitou o Push Web para uso próprio

Esta nova forma de comunicação na Web tradicional é incrível por diversos motivos, entre eles:

– Você poderá se comunicar com os visitantes que “jamais” preencheriam o e-mail em um formulário, com isso você pode engajá-los via push até que eles percebam valor em seu produto e decidam deixar seu contato.

– Se o visitante ou lead estiver no mobile lendo seu conteúdo ou visitando seu site e aceitar o push então, o push será enviado para o SmartPhone de forma muito semelhante ao Push de um App.

– Incrível: Hoje as taxas de abertura de emails estão em torno de 10%, em média, ou seja a cada 100 emails enviados apenas 10 abrem e lêem. Já a taxa de cliques está em torno de 30%, em suma, você envia 100 emails e apenas 30 pessoas clicam para ir ao seu site.

Usando o Push Web você vai poder engajar justamente estes contatos que não interagem com você nos e-mails, então se apenas 10% visualizarem e 30% clicarem (mesmas taxas de um e-mail marketing) você vai conseguir dobrar o resultado de suas ações de marketing e conversões.

Web To Lead

Identificação de contatos via formulário

Crie seus próprios formulários dentro do seu site para capturar contatos e envie diretamente para a Jeenga.

Todos os atributos de contatos da Jeenga podem ser enviados com o uso do formulário. Inclusive atributos dinâmicos. (Ver Exemplo 1).
É possível enviar um evento junto com o mesmo formulário. (Ver Exemplo 2).

Endpoint: https://api.jeenga.com/jeenga-api/form/customer
Método HTTP: post

Parâmetros obrigatórios

j_apikey É a chave de identificação fornecida pela Jeenga (Encontrada no seu menu Integrações da plataforma Jeenga).
identifier ID único do Cliente (ele é responsável também por marcar seu contato como um cliente).
redirect_to URL para o qual o usuário deve ser redirecionado após o envio do formulário.

Exemplo 1: Envio de nome, e-mail e um atributo dinâmico

<form name="jeengaForm" action="https://api.jeenga.com/jeenga-api/form/customer" method="post" onsubmit="jeengaForm.identifier.value=jeengaForm.email.value">
	<input type="hidden" name="j_apikey" value="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" /><!-- required -->
	<input type="hidden" name="identifier" /><!-- required -->
	<input type="hidden" name="redirect_to" value="http://www.your-web-site-here.com?your-parameter=ok" /><!-- required -->
	<table>
		<tr>
			<td>Nome</td>
			<td><input type="text" name="name" /></td>
		</tr>
		<tr>
			<td>E-mail</td>
			<td><input type="text" name="email" /></td>
		</tr>
		<tr>
			<td>Atributo Dinâmico 1</td>
			<td><input type="text" name="atributo_dinamico_1" /></td>
		</tr>
		<tr>
			<td></td>
			<td><input type="submit" /></td>
		</tr>
	</table>
</form>

Exemplo 2: Envio de nome, e-mail e um evento.

<form name="jeengaForm" action="https://api.jeenga.com/jeenga-api/form/customer" method="post" onsubmit="jeengaForm.identifier.value=jeengaForm.email.value">
	<input type="hidden" name="j_apikey" value="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" /><!-- required -->
	<input type="hidden" name="identifier" /><!-- required -->
	<input type="hidden" name="redirect_to" value="http://www.your-web-site-here.com?your-parameter=ok" /><!-- required -->
	<input type="hidden" name="activity.event" value="Registrated" />
	<input type="hidden" name="activity.module" value="Registration" />
	<input type="hidden" name="activity.channel" value="Site" />
	<table>
		<tr>
			<td>Nome</td>
			<td><input type="text" name="name" /></td>
		</tr>
		<tr>
			<td>E-mail</td>
			<td><input type="text" name="email" /></td>
		</tr>
		<tr>
			<td></td>
			<td><input type="submit" /></td>
		</tr>
	</table>
</form>

Redirecionamento após o envio

Após o envio do formulário, o usuário será redirecionado para a URL fornecida através do parâmetro “redirect_to”.
Parâmetros de status são retornados via queryString para a URL de retorno, são eles:

j_status Status da operação (0: OK, 1: Customer inserido mas problemas na inserção da atividade, -1: Erro).
j_message Em caso de j_status não OK, uma mensagem explicativa sobre o problema.

Baixar um arquivo de exemplo: Integração via Formulário

Java Script

Introdução

Esse documento tem a finalidade de facilitar a compreensão de todos que desejam entender o funcionamento e implementação da integração por Java Script com a Jeenga. O primeiro passo é saber como é feita a segmentação automática dos contatos cadastrados: Clientes, Leads e Visitantes.

Contato

Qualquer registro de pessoas (Cliente, Lead, Visitante).

Cliente

Qualquer contato que esteja marcado como cliente manualmente na plataforma ou via integração. São também aqueles contatos que tenham um identificador (ID) como parâmetro.

Lead

Qualquer contato que não seja um Cliente, mas que possua informações de contato (email ou telefone/celular).

Visitante

Qualquer contato que não seja Cliente ou Lead e acessou sua página integrada a Jeenga.

Atributos normalizados de um Contato

Os atributos normalizados são os campos padronizados com o nome e tipo de dado específico. Esses dados serão gravados e utilizados durante a criação de suas campanhas ou segmentações.

Veja abaixo a lista dos atributos normalizados:

identifier ID, identificador único do seu Cliente (ele é responsável também por marcar seu contato como um cliente na segmentação automática).
name Nome do Contato.
email E-mail do Contato.
customer_type Indica qual o tipo de contato (CLIENT, LEAD ou VISITOR).
phone_number Número de telefone do Contato (formato: +551198765432).
mobile Número de celular do Contato (formato: +5511987654321).
gender Gênero (sexo) do Contato (formato: M ou F).
avatar Imagem/Foto do Contato (formato: https://…).
birthday Data de nascimento do Contato (formato: 2015-07-25T09:30:15.000Z).
created_at Data de cadastro do Contato. Se não for informada, será utilizada a data de cadastro na Jeenga. (formato: 2015-07-21T09:30:15.000Z).
gcm_token Token para envio de Push Notification no android.
apns_token Token para envio de Push Notification no iOS.
onesignal_player_id ID fornecido pela API OneSignal. Utilizado para envio de push browser.
blocked_email Flag indicando se o envio de e-mails provenientes de campanhas foram bloqueados para este contato (true: não recebe e-mails, false: recebe e-mails).
blocked_sms Flag indicando se o envio de sms provenientes de campanhas foram bloqueados para este contato (true: não recebe sms, false: recebe sms).
blocked_mobile_push Flag indicando se o envio de push mobile provenientes de campanhas foram bloqueados para este contato (true: não recebe push mobile, false: recebe push mobile).
blocked_browser_push Flag indicando se o envio de push browser provenientes de campanhas foram bloqueados para este contato (true: não recebe push browser, false: recebe push browser).

Atributos dinâmicos de um Contato

Um contato pode possuir qualquer atributo dinâmico. Os atributos são separados em 5 categorias de tipos de dados que facilitam o momento da criação de filtros para Listas/Campanhas quando enviados corretamente. As categorias são:

Texto Qualquer sequência de caracteres (exemplo: “abc”, “status_online”).
Número Qualquer sequência numérica (exemplo: 1, 999.1 , 98178465.99 | o separador decimal é ponto “.”).
Booleano Verdadeiro ou Falso (exemplo: true, false).
Data Utilizando o padrão ISO 8601 no formato YYYY-MM-DDTHH:mm:ss.SSSZ (exemplo: DE: 21/07/2015 09:30:15 -> PARA: 2015-07-21T09:30:15.000Z).
Geolocation (In Dev.).

Integração do Java Script

Veja abaixo a explicação de cada trecho do Java Script de integração com a Jeenga. Sua implementação vai variar de acordo com suas necessidades de negócio.

Identificação da sua empresa

Esse trecho de código Java Script deve ser colocado em todas as páginas do site. Ele é responsável por identificar sua empresa para a Jeenga, pelo API_KEY que está disponível no menu “Integração”. *Recomendamos implementar esse trecho no cabeçalho (header) do seu site:

//API_KEY é único para cada cliente da Jeenga.
window.JeengaOptions = {
	API_KEY: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" //Esta é a chave da API fornecida pela Jeenga e está disponível no menu Integração.
};

//Carregamento do JS Jeenga
(function() {
	var c = console, w = window, _ = [], r = function() {for(var i=0; i < _.length; i++) {var o = _[i];try {w.JeengaApi[o.f].apply(o.t, o.a);} catch(e){if(c && c.error)c.error(e);};}}; w.JeengaApiReady = r;
	var nli = function() {_.push({f:"identify",t:this,a:arguments});}, nlt = function() {_.push({f:"track",t:this,a:arguments});}; w.JeengaApi = {identify:nli,track:nlt};
	var js = "s3.amazonaws.com/jeenga/js/v0.1/jeenga.js";
	var protocol = ("https:" == document.location.protocol ? "https://" : "http://");
	var j = document.createElement("script"); j.type = "text/javascript"; j.async = true; j.src = protocol + js;
	var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(j, s);
})();

Observação Importante: O carregamento do JS é feito de forma assíncrona, isso quer dizer que não aguarda o retorno do servidor para ser interpretado como operação de sucesso.

Identificação do contato

Esse bloco é responsável por identificar o seu contato para a Jeenga, beneficiando-se da função JavaScript que é executada quando o JS Jeenga é carregado, podendo identificar o Contato no momento correto em que se cadastra ou se autentica em seu site. Normalmente ele deve ser carregado quando o contato preenche um formulário (form) em seu site, ou, caso já seja um cliente e tenha acesso ao seu ambiente restrito (caso exista esse processo em seu negócio), se autentique em seu site. Contamos também com alguns exemplos de como coletar os dados dos formulários de seu site. Caso tenha interesse podemos enviar para você.
Exemplo:

//Obtém o ID do Contato.
var identifier = getUserId();

//Obtém os dados do Contato. Pode conter atributos normalizados ou dinâmicos.
var data = {
	name: getName(),
	avatar: getAvatar(),
	birthday: getBirthday(),
	dynamic_param: "user_dynamic_param",
	user_credits: getUserCredits()
};

//Passa os dados de identificação do contato para a Jeenga.
JeengaApi.identify(identifier, data);

Captura de eventos

Esse bloco é responsável por capturar os eventos realizados pelo contato dentro do seu site (Eventos de clique, preenchimento de formulários, etc…).
Exemplo 1:

//Capturando evento de clique em um site de notícias
var event = "Clicou no link X";
var channel = "WebSite";
var module = "Área de Notícias";
JeengaApi.track(event, channel, module);

//Adicionalmente pode ser utilizado um parâmetro com dados extras.
var data = {
	titulo: "Título da Nóticia",
	subtitulo: "Subtitulo da Nóticia"
};

//Passa os dados do evento para a Jeenga.
JeengaApi.track(event, channel, module, data);

Exemplo 2:

//Capturando uma conversão
var event = "Converteu";
var channel = "WebSite";
var module = "Pagamento";
var data = {
	conversion_value: 1,
	conversion_amount: 9.99,
	description: "Comprou o produto X no valor de R$ 9,99"
};

//Passa os dados do evento para a Jeenga.
JeengaApi.track(event, channel, module, data);

Identificação do browser (Para envio de push browser)

Este bloco é utilizado para identificar o browser do contato, de modo a enviar mensagens de push notification.
A API OneSignal é utilizada para obter os dados necessários para o envio. Clique aqui para conhecer o OneSignal.

//Obtém os dados necessários
var data = {
	onesignal_player_id: "PLAYER ID OBTIDO A PARTIR DO ONESIGNAL."
};

//Passa os dados do browser para a Jeenga.
JeengaApi.browser(data);

Veja também os exemplos de html e php para tomar como base.

Obs: O arquivo php está em formato html. Por favor salve como php para conseguir visualizar corretamente.

 

Web Service

Identificação de Usuários

Endpoint: https://api.jeenga.com/jeenga-api/customer
(Os parâmetros devem ser passados como QueryString usando os métodos POST ou GET)

Parâmetros obrigatórios

j_apikey É a chave de identificação fornecida pela Jeenga (Encontrada no seu menu Integrações da plataforma Jeenga).
identifier ID único do Cliente (ele é responsável também por marcar seu contato como um cliente).

Parâmetros opcionais reconhecidos pela Jeenga

name Nome do Contato.
email E-mail do Contato.
customer_type Indica qual o tipo de contato (CLIENT, LEAD ou VISITOR).
phone_number Número de telefone do Contato (formato: +551198765432).
mobile Número de celular do Contato (formato: +5511987654321).
gender Gênero(sexo) do Contato (formato: M ou F).
avatar Imagem/Foto do Contato (formato: https://…).
birthday Data de nascimento do Contato (formato: 2015-07-25T09:30:15.000Z).
created_at Data de cadastro do Contato. Se não for informada, será utilizada a data de cadastro na Jeenga. (formato: 2015-07-21T09:30:15.000Z).
gcm_token Token para envio de Push Notification no android.
apns_token Token para envio de Push Notification no iOS.
onesignal_player_id ID fornecido pela API OneSignal. Utilizado para envio de push browser.
blocked_email Flag indicando se o envio de e-mails provenientes de campanhas foram bloqueados para este contato (true: não recebe e-mails, false: recebe e-mails).
blocked_sms Flag indicando se o envio de sms provenientes de campanhas foram bloqueados para este contato (true: não recebe sms, false: recebe sms).
blocked_mobile_push Flag indicando se o envio de push mobile provenientes de campanhas foram bloqueados para este contato (true: não recebe push mobile, false: recebe push mobile).
blocked_browser_push Flag indicando se o envio de push browser provenientes de campanhas foram bloqueados para este contato (true: não recebe push browser, false: recebe push browser).

Observações

A Jeenga aceita qualquer outro parâmetro do seu contato. Esse parâmetro é gravado e será identificado como atributo personalizado do seu Contato.

Exemplo chamado

curl https://api.jeenga.com/jeenga-api/customer?j_apikey=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&identifier=1234&name=Joaquim%20Silva&email=joaquim%40email.com

Tracking de atividades

API Endpoint: https://api.jeenga.com/jeenga-api/activity
(Os parâmetros devem ser passados como QueryString usando os métodos POST ou GET).

Parâmetros obrigatórios

j_apikey É a chave de identificação fornecida pela Jeenga (Encontrada no seu menu Integrações da plataforma Jeenga).
identifier ID único do Contato (Relaciona esta atividade a um Contato).
event Nome do evento que está sendo trackeado. (ex: clicou em comprar, cadastrou, deslogou, tentou comprar, não comprou, finalizou a compra).
module Módulo do evento (Ex: Login, logout, cadastro, landpage, produto, carrinho).
channel Canal do evento (ex: APP, Site, Ecommerce, Ibeacon, PDV Loja).

Parâmetros opcionais reconhecidos pela Jeenga

conversion_value Utilizado em eventos de conversão para contabilizar a quantidade de conversões que um determinado contato fez (ex: Número Inteiro: 1, 2, 10).
conversion_amount Utilizado em eventos de conversão para contabilizar o valor gasto por um determinado contato (ex: Valor monetário: 1.99, 9.90, 54.90, 100).

Observações

A Jeenga aceita qualquer outro parâmetro do seu contato. Esse parâmetro é gravado e será identificado como atributo personalizado do seu Contato.

Exemplo chamado

curl https://api.jeenga.com/jeenga-api/activity?j_apikey=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&event=Play&module=Games&channel=Mobile&identifier=1234