Esta página descreve os passos necessários para integração IOS com a Dito.

Download do SDK

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

Criando o certificado SSL

O primeiro passo é criar um App ID e o certificado SSL associado no site da Apple Developer Member Center. Este certificado irá permitir que o servidor envie push notifications para a aplicação identificado pelo App ID.

Pedido de Certificado

Para começar, vamos precisar de um arquivo de solicitação para a assinatura do certificado. Isto será utilizado para autenticar a criação do certificado SSL.

  1. Inicie a aplicação "Keychain Access" no Mac.

  2. Selecione o item do menu “Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority…”.

879
  1. Digite seu e-mail e nome.

  2. Selecione “Saved to disk” para realizar o download do arquivo .certSigningRequest.

617

Criando um App ID

Toda aplicação iOS instalado no dispositivo do desenvolvedor necessita de um App ID. Como convenção, são representados por endereços invertidos (ex.: com.example.MyPushApp).

  1. Navegue no site do Apple Developer Member Center e selecione Certificates, Identifiers & Profiles.
  2. Selecione Identifiers na seção iOS Apps.
  3. Você verá a lista de seus iOS App IDs. Selecione o botão + para registrar um novo App ID.
976
  1. Digite um nome para seu novo App ID e marque o checkbox para habilitar o serviço de Push Notifications, localizado abaixo de App Services.
674 672
  1. Abaixo de App ID Suffix selecione Explicit App ID. Digite o Bundle ID de seu ap iOS. Esta string deve ser igual ao Bundle Identifier no arquivo Info.plist em seu app iOS.
668
  1. Selecione “Continue” e depois “Submit” para finalizar o registro.

Configurando o App ID para Push Notification

Agora que você criou um App ID, é hora de configurar o App ID para Push Notifications.

  1. Selecione o novo App ID criado da lista de iOS App IDs, então selecione “Edit”.
723
  1. Desça até a seção de Push Notifications. Aqui você será capaz de criar tanto um Certificado SSL de desenvolvimento bem como uma de produção. Comece selecionando “Create Certificate” em “Development SSL Certificate”.
679
  1. A próxima tela mostrará instruções para criar um Certificate Signing Request (CSR). Isto é o mesmo arquivo .certSigningRequest criado anteriormente. Selecione “Continue”, então escolha “Choose File...” e coloque esse arquivo.
  2. Selecione “Generate”. Uma vez que o certificado estiver pronto, selecione “Done” e depois realize o download do certificado.
677
  1. Clique duas vezes no certificado SSL baixado para instalá-lo em seu Keychain.
  2. No Keychain Access, dentro de “My Certificates”, procure o certificado que você adicionou.
879
  1. Clique com o botão direito, selecione "Export Apple Development IOS Push Services:..." e salve como arquivo .p12. Você será solicitado para digitar uma senha que será usada para proteger o certificado exportado. Não digite uma senha de exportação quando solicitado!

Criando um Provisioning Profile

Um Provisioning Profile autentica seu dispositivo a rodar o app que você está desenvolvendo. Se você tiver criado um novo App ID ou alterado um existente você vai precisar gerar novamente o Provisioning Profile e instalá-lo. Se você tiver problemas ao usar um profiling existente, tente remover o App ID e configurá-lo novamente, Neste tutorial iremos criar um novo.

  1. Navegue no website Apple Developer Member Center e selecione Certifies, Identifiers & Profiles.

  2. Selecione Provisioning Profiles na seção iOS Apps.

  3. Selecione o botão + para criar um novo Provisioning Profile.

  4. Escolha “iOS App Development” como seu tipo de Provisioning Profile e clique em “Continue”.

  5. Escolha o App IS que foi criado no e clique em “Continue”.

  6. Selecione seu certificado de desenvolvedor iOS na próxima tela e clique em “Continue”.

  7. Você será solicitado para selecionar quais dispositivos srão incluídos no Provisioning Profile. Clique em “Continue” depois de selecionar quais dispositivos serão testados.

  8. Escolha um nome para esse Provisioning Profile e clique em “Generate”.

  9. Baixe o Provisioning Profile gerado clicando no botão “Download”.

  10. Instale o profile clicando duas vezes no arquivo baixado.

Desenvolvendo o código de Push Notification integrado com a Dito

Na plataforma da Dito será necessário adicionar o certificado no formato .pem, para isso será necessário converter o arquivo .p12 para .pem:

$ openssl pkcs12 -in cert.p12 -out apple_push_notification.pem -nodes -clcerts

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

Adicionar as seguintes dependencias em seu projeto:

  • SystemConfiguration.framework

  • Security.framework

Em AppDelegate.m:

  • Importe o seguinte header para seu projeto:
#import <DitoSDK/DitoAPI.h>
  • Insira a propriedade:
@interface AppDelegate ()

@property DitoCredentials *credentials;

@end
  • Initialize o SDK:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Inicializar as notificações

    UIUserNotificationType userNotificationTypes = (UIUserNotificationTypeAlert |
                                                    UIUserNotificationTypeBadge |
                                                    UIUserNotificationTypeSound);

    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:userNotificationTypes
                                                                             categories:nil];
    [application registerUserNotificationSettings:settings];
    [application registerForRemoteNotifications];

    // Inicializar o SDK Dito

    [DitoAPI configure:@"SUA_API_KEY" secret:@"SEU_SECRET_KEY"];

    self.credentials = [[DitoCredentials alloc] initWithID:@"DITO_IOS_USER" facebookID:nil reference:nil];
    NSDictionary *user = @{ @"email": @"[email protected]", @"name": @"Dito IOS" };
    
    [DitoAPI identify:self.credentials accessToken:nil data:user completion:nil];
   
    return YES;
}

Observação: Substitua as variáveis SUA_API_KEY e SUA_SECRET pelas suas chaves da Dito.

    • Registre o token do IOS:
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

    // Registrar o token do dispositivo com o webservice da Dito
    NSString * deviceTokenString = [[[[deviceToken description]
              stringByReplacingOccurrencesOfString: @"<" withString: @""]
              stringByReplacingOccurrencesOfString: @">" withString: @""]
              stringByReplacingOccurrencesOfString: @" " withString: @""];
    
    [DitoAPI registerDevice:self.credentials deviceToken:deviceTokenString completion:^(id response, NSError *error) {
        NSLog(@"registerDeviceCompletion - response: %@", response);
        NSLog(@"registerDeviceCompletion - error: %@", error);
    }];
        
}
  • Responda para o servidor ao abrir push notification:
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {

    NSNumber *notification = [userInfo objectForKey:@"notification"];
    NSString *link = [userInfo objectForKey:@"link"];
    NSString *notificationJSON = [NSString stringWithFormat:@"{ \"notification\": \"%@\", \"link\": \"%@\" }", notification, link];

    [DitoAPI notificationRead:self.credentials message:notificationJSON completion:^(id response, NSError *error) {
        NSLog(@"registerDeviceCompletion - response: %@", response);
        NSLog(@"registerDeviceCompletion - error: %@", error);
    }];
}
  • Verifique se ocorreu um erro na notificação:
- (void)application:(UIApplication *)application
didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
    NSLog(@"Error: %@", error);
}

Definições do SDK

Configuração

[DitoAPI configure:@"SUA_API_KEY" secret:@"SEU_SECRET"];

Parâmetros de configure

ParâmetroObrigatórioTipoDefaultDescrição
apiKeySimString-API Key da sua aplicação na Dito.
secretSimString-Secret da sua aplicação na Dito.

Identificando seus usuários

Toda comunicação com a Dito através do SDK para iOS 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.

DitoCredentials *credentials = [[DitoCredentials alloc] initWithID:@"`userID`" facebookID:@"`facebookID`" reference:@"`reference`"];

Parâmetros de DitoCredentials

ParâmetroObrigatórioTipoDefaultDescrição
userIDSimString-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.
facebookIDSimString-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.
referenceSimString-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 nil.

Exemplo: Usuário da sua base

DitoCredentials *credentials = [[DitoCredentials alloc] initWithID:@"ID_DO_USUARIO_NA_SUA_BASE" facebookID:nil reference:nil];

Exemplo: Usuário do Facebook

DitoCredentials *credentials = [[DitoCredentials alloc] initWithID:nil facebookID:@"FACEBOOK_ID" reference:nil];

Cadastrando/Logando um usuário

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

📘

É recomendado uso do método DitoAPI 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.

[DitoAPI identify:`credentials` accessToken:`accessToken` data:`userData` completion: `completion`];

Parâmetros de identify

ParâmetroObrigatórioTipoDefaulDescrição
credentialsSimDitoCredentials-Objeto com a identificação do usuário.
accessTokenNãoString-Access Token do usuário relacionado a uma das redes sociais suportadas pela Dito.
userDataNãoNSDictionary-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.
completionNãoFunction-Função de callback chamada quando o método terminar de ser executado. Exemplo:

^(id response, NSError *error) { // Tratar retorno aqui }

Exemplo: DitoAPI identify

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

DitoCredentials *credentials = [[DitoCredentials alloc] initWithID:@"{{ID_DO_USUARIO_NA_SUA_BASE}}" facebookID:nil reference:nil];

NSDictionary *userData = @{
                            @"nome_do_seu_dado_customizado": @"Valor do seu dado customizado"
                            };

NSData *userDataSerialized = [NSJSONSerialization dataWithJSONObject:userData options:0 error:nil];
NSString *userDataSerializedString = [[NSString alloc] initWithData:userDataSerialized encoding:NSUTF8StringEncoding];

NSDictionary *user = @{
                      @"email": @"EMAIL",
                      @"name": @"NOME",
                      @"birthday": @"DATA_NASCIMENTO",
                      @"location": @"CIDADE",
                      @"data": userDataSerializedString
                      };

[DitoAPI identify:credentials accessToken:nil data:user completion:nil];

Acompanhamento de eventos

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

[DitoAPI track:`credentials` event: `event` completion: `completion`];

Parâmetros de track

ParâmetroObrigatórioTipoDefaultDescrição
credentialsSimDitoCredentials-Objeto com a identificação do usuário.
eventSimNSDictionary-Objeto com as informações do evento. É recomendado o uso de um objeto JSON. Veja o exemplo abaixo.
completionNãoFunction-Função de callback chamada quando o método terminar de ser executado. Exemplo:

^(id response, NSError *error) { // Tratar retorno aqui }

Exemplo: DitoAPI 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:

NSDictionary *event = @{
  @"action": @"nome-do-evento",
  @"revenue": @{{receita-gerada-pelo-evento}}, // Se o evento lhe rendeu alguma receita, você pode nos enviá-la pela propriedade "revenue". Ex: @99.9
  @"data": @{
    @"nome_da_propriedade_do_evento": @"Valor da propriedade do evento"
  }
};

[DitoAPI track:credentials event: event completion:nil];

Alias

O método DitoAPI 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:

DitoAccount *account = [[DitoAccount alloc] initWithID:@"FACEBOOK_ID" accessToken:@"ACCESS_TOKEN" type:FACEBOOK];
NSArray *accounts = @[account];

[DitoAPI alias:credentials accounts:accounts completion:nil];

Unalias

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

DitoAccount *account = [[DitoAccount alloc] initWithID:@"FACEBOOK_ID" type:FACEBOOK];
NSArray *accounts = @[account];

[DitoAPI unalias:credentials accounts:accounts completion:nil];

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 a explicação da Apple 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

[DitoAPI registerDevice:credentials deviceToken:@"TOKEN_DE_PERMISSAO_DO_USUARIO" completion:nil];

Removendo um token do usuário

[DitoAPI unregisterDevice:credentials deviceToken:@"TOKEN_DE_PERMISSAO_DO_USUARIO" completion:nil];

Formato da notificação

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

{
  "aps": {
    "alert": "MESSAGE",
    "sound": "default",
    "priority": 10,
    "content_available": 1,
    "badge: 0
  },
  "notification": "ID_DA_NOTIFICACAO",
  "link": "DEEP_LINK_DA_NOTIFICACAO"
}

📘

A mensagem da notificação será enviada dentro do nó alert.

Leitura da 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.

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
 NSNumber *notification = [userInfo objectForKey:@"notification"];
 NSString *link = [userInfo objectForKey:@"link"];
 NSString *notificationJSON = [NSString stringWithFormat:@"{ \"notification\": \"%@\", \"link\": \"%@\" }", notification, link];

    [DitoAPI notificationRead:self.credentials message:notificationJSON completion:nil];
}