Download do SDK

Faça o download do SDK para Android da Dito para fazer sua integração.

Instalação

Para instalar o SDK para Android da Dito em seu projeto, basta seguir os seguintes passos:

Copiar o arquivo DitoSDK.aar para seu projeto;
Adicionar o arquivo DitoSDK.aar como dependência. Clique com o botão direito em cima do arquivo e selecione "Add As Library";
Adicionar a biblioteca GSON como dependência em seu projeto. No arquivo app/build.gradle, adicione a linha compile 'org.immutables:gson:2.0.6' em suas dependências. Caso você ja tenha colocado, ignore este passo.

Configuração

Importe as classes abaixo para seu projeto:

import br.com.dito.ditosdk.DitoSDK;
import br.com.dito.ditosdk.exception.DitoSDKException;
import br.com.dito.ditosdk.interfaces.DitoSDKCallback;
import br.com.dito.ditosdk.model.DitoAccount;
import br.com.dito.ditosdk.model.DitoCredentials;
import br.com.dito.ditosdk.constant.Constants;

import com.google.gson.JsonObject;

Adicione o código abaixo no Singleton ou no onCreate da Acitivity.
Observação: Substitua as variáveis {{SUA_API_KEY}} e {{SUA_SECRET}} pelas suas chaves da Dito.

try {
  DitoSDK.configure(this, "{{SUA_API_KEY}}", "{{SUA_SECRET}}");
} catch (DitoSDKException e){}

Dito.SDK.configure(`this`, `apiKey`, `secret`);

Parâmetro	Obrigatório	Tipo	Default	Descrição
this	Sim	Context	-	Contexto da sua aplicação
apiKey	Sim	String	-	`API Key` da sua aplicação
secret	Sim	String	-	`Secret` da sua aplicação

Importante: Para o funcionamento correto do SDK, as seguintes permissões são necessárias no aplicativo:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Identificando seus usuários

Toda comunicação com a Dito através do SDK para Android em que um usuário for necessário, será obrigatório o envio de um objeto do tipo DitoCredentials com o ID do usuário.
Esse objeto é criado pelo método abaixo.

new DitoCredentials(`userID`, `facebookID`, `reference`);

Parâmetro	Obrigatório	Tipo	Default	Descrição
userID	Sim	String	-	ID do usuário em seu banco de dados. Se essa informação não for necessária, você precisa passar esse parâmetro com o valor `null`.
facebookID	Sim	String	-	ID do usuário no Facebook. Você conseguirá esse ID no processo de login com o Facebook. Se essa informação não for necessária, você precisa passar esse parâmetro com o valor `null`.
reference	Sim	String	-	ID do usuário na Dito. Esse ID é retornado quando o usuário é enviado pela Dito. Se essa informação não for necessária, você precisa passar esse parâmetro com o valor `null`.

🚧
Somente um dos parâmetros acima é obrigatório. Os outros valores deverão ser enviados com o valor null.

Exemplo: Usuário da sua base

// Adicione essa declaração de variável em um contexto global
// para que você consiga acessar a credencial do usuário de qualquer lugar do seu código
private DitoCredentials credentials;

credentials = new DitoCredentials("{{ID_DO_USUARIO_NA_SUA_BASE}}", null, null, null, null);

Exemplo: Usuário do Facebook

// Adicione essa declaração de variável em um contexto global
// para que você consiga acessar a credencial do usuário de qualquer lugar do seu código
private DitoCredentials credentials;

credentials = new DitoCredentials(null, "{{FACEBOOK_ID}}", null, null, null);

Cadastrando/Logando um usuário

O envio de seus usuários para a Dito se dá pelo método DitoSDK.identify.

📘
É recomendado uso do método DitoSDK.identify sempre que o usuário abrir o aplicativo. Dessa forma garantimos que o usuário tenha evento de login todos os dias que ele usar o aplicativo.

DitoSDK.identify(`credentials`, `accessToken`, `userData`, `completion`);

Parâmetro	Obrigatório	Tipo	Default	Descrição
credentials	Sim	DitoCredentials	-	Objeto com a identificação do usuário.
accessToken	Não	String	-	Access Token do usuário relacionado a uma das redes sociais suportadas pela Dito.
userData	Não	Object	-	Objeto com as informações do usuário, como: nome, email e dados personalizados. É recomendado o uso de um objeto JSON. Veja o exemplo abaixo.
completion	Não	DitoSDKCallback	-	Função de callback chamada quando o método terminar de ser executado. Exemplo: `new DitoSDKCallback() { @Override public void onSuccess(String response) {} @Override public void onError(Exception e) {} }`

Exemplo: DitoSDK.identify

Observação: Substitua as informações em {{...}} de acordo com seu usuário.

try {
  JsonObject userData = new JsonObject();
  JsonObject customData = new JsonObject();

  userData.addProperty("email", "{{EMAIL}}");
  userData.addProperty("name", "{{NOME}}");
  userData.addProperty("birthday", "{{DATA_NASCIMENTO}}"); // Formato: YYYY-MM-DD
  userData.addProperty("location", "{{CIDADE}}");

  customData.addProperty("{{NOME_DO_SEU_DADO_CUSTOMIZADO}}", "{{VALOR_DO_SEU_DADO_CUSTOMIZADO}}");
  userData.addProperty("data", customData.toString());

  DitoSDK.identify(credentials, null, userData, null);
} catch (DitoSDKException e) {}

Acompanhamento de eventos

O acompanhamento de eventos na Dito se dá pelo método DitoSDK.track.

DitoSDK.track(`credentials`, `event`, `completion`);

Parâmetro	Obrigatório	Tipo	Default	Descrição
credentials	Sim	DitoCredentials	-	Objeto com a identificação do usuário.
event	Sim	Object	-	Objeto com as informações do evento. É recomendado o uso de um objeto JSON. Veja o exemplo abaixo.
completion	Não	DitoSDKCallback	-	Função de callback chamada quando o método terminar de ser executado. Exemplo: `new DitoSDKCallback() { @Override public void onSuccess(String response) {} @Override public void onError(Exception e) {} }`

Exemplo: DitoSDK.track

Observação: Substitua as informações em {{...}} de acordo com cada evento.

ATENÇÃO

Os nomes dos eventos DEVEM ser enviados para a Dito em letras minúsculas, sem acentuação ou caracteres especiais. Caso o nome de suas ações seja composto por mais de uma palavra, estas devem ser separadas por hífen '-' conforme o exemplo abaixo:

try {
  JsonObject event = new JsonObject();
  JsonObject eventData = new JsonObject();

  event.addProperty("action", "{{nome-do-evento}}");

  // Se o evento lhe rendeu alguma receita, você pode nos enviá-la pela propriedade "revenue"
  event.addProperty("revenue", {{RECEITA_GERADA_PELO_EVENTO}});

  eventData.addProperty("{{nome_da_propriedade_do_evento}}", "{{Valor propriedade do evento}}");
  event.addProperty("data", eventData.toString());

  DitoSDK.track(credentials, event, null);
} catch (DitoSDKException e) {}

Alias

O método DitoSDK.alias é usado para associar um usuário novo a um usuário existente.

Por exemplo, você pode associar um usuário do Facebook a um usuário que já está cadastrado na Dito previamente.

Utilize o código abaixo para associar um usuário:

try {
  List<DitoAccount> ditoAccountList = new ArrayList<>();

  ditoAccountList.add(new DitoAccount("{{FACEBOOK_ID}}", "{{ACCESS_TOKEN_DO_FACEBOOK}}", Constants.AccountsType.FACEBOOK));
  DitoSDK.alias(credentials, ditoAccountList, null);

} catch (DitoSDKException e) {}

Unalias

O método DitoSDK.unalias tem a mesma estrutura do DitoSDK.alias, com uma diferença: esse método desassocia um usuário, ou seja, ele desfaz o que o método DitoSDK.alias faz.

try {
  List<DitoAccount> ditoAccountList = new ArrayList<>();

  ditoAccountList.add(new DitoAccount("100009681031777", null, Constants.AccountsType.FACEBOOK));
  DitoSDK.unalias(credentials, ditoAccountList, null);

} catch (DitoSDKException e) {}

Notificações push

Para que você consiga enviar notificações push com seu aplicativo usando a Dito, você precisa nos enviar o token de permissão do usuário.

Esse token é o que permite ou não o envio de notificação para cada usuário da sua base. Sem o envio desse token usuário não receberá notificação push.

Acesse o tutorial do Google e entenda como obter o token de permissão do usuário para que você possa enviar para a Dito.

Enviando o token do usuário

DitoSDK.registerDevice(credentials, "{{TOKEN_DE_PERMISSAO_DO_USUARIO}}"

Removendo um token do usuário

DitoSDK.unregisterDevice(credentials, "{{TOKEN_DE_PERMISSAO_DO_USUARIO}}"

Formato da notificação

A Dito enviará as notificações push para seu aplicativo no seguinte formato:

{
  "notification": "{{ID_DA_NOTIFICACAO}}",
  "details": {
    "link": "{{DEEP_LINK_DA_NOTIFICACAO}}",
    "message": "{{MENSAGEM_DA_NOTIFICACAO}}"
  }
}

Leitura de notificação

Quando o usuário abrir uma notificação, o método DitoSDK.notificationRead deverá ser chamado passando o JSON enviado pela Dito como parâmetro.

try {
  // Esse JSON será enviado no push pela Dito.
  String notificationJSON = "{ \"notification\": \"{{ID_DA_NOTIFICACAO}}\", \"details\": { \"link\": \"{{DEEP_LINK_DA_NOTIFICACAO}}\", \"message\": \"{{MENSAGEM_DA_NOTIFICACAO}}\" } }";

  DitoSDK.notificationRead(credentials, notificationJSON, null);
} catch (DitoSDKException e) {}

Download do SDK

Instalação

Configuração

Dito.SDK.configure(this, apiKey, secret);

Identificando seus usuários

new DitoCredentials(userID, facebookID, reference);

🚧

Exemplo: Usuário da sua base

Exemplo: Usuário do Facebook

Cadastrando/Logando um usuário

📘

DitoSDK.identify(credentials, accessToken, userData, completion);

Exemplo: DitoSDK.identify

Acompanhamento de eventos

DitoSDK.track(credentials, event, completion);

Exemplo: DitoSDK.track

Alias

Unalias

Notificações push

Enviando o token do usuário

Removendo um token do usuário

Formato da notificação

Leitura de notificação

Dito.SDK.configure(`this`, `apiKey`, `secret`);

new DitoCredentials(`userID`, `facebookID`, `reference`);

DitoSDK.identify(`credentials`, `accessToken`, `userData`, `completion`);

DitoSDK.track(`credentials`, `event`, `completion`);