Ir para o conteúdo

Integração em aplicativos móveis iOS

Este artigo fornece informações sobre a integração do Rox.Chat Mobile SDK versão 3 em seu aplicativo iOS.

Configuração

CocoaPods

O Rox.Chat Mobile SDK está disponível via CocoaPods (repositório). Para instalar o SDK, você precisa adicionar ao seu Podfile o target desejado:

pod 'RoxchatClientLibrary'

A diretiva use_frameworks! deve ser especificada no Podfile.

Aplicativo de exemplo

Para executar o exemplo, "clone" o repositório e execute o comando pod install no diretório Example.

Se você não tiver o CocoaPods instalado, deverá instalá-lo antes de fazer isso com o comando no terminal:

sudo gem install cocoapods.

Uso

Diferentemente da interface da Web, o aplicativo móvel no Rox.Chat Mobile SDK não verifica se há operadores disponíveis (on-line). Em outras palavras, o chat móvel sempre presume que o botão de chamada do operador está sempre no status "online". O Rox.Chat Mobile SDK sempre permite iniciar um bate-papo; no entanto, se não houver operadores prontos para responder nesse bate-papo, o cliente ficará sozinho no bate-papo até que o operador apareça ou o bate-papo seja encerrado por tempo limite.

O Rox.Chat suporta a conexão de vários aplicativos móveis iOS diferentes ao Rox.Chat Server em uma única conta de cliente.

O Rox.Chat Mobile SDK for iOS suporta a seleção de posicionamento ao criar um chat. Recomendamos sempre criar pelo menos um canal separado para um aplicativo móvel. Se houver vários aplicativos móveis, no mínimo um canal para cada MP.

A interação do chat ocorre em uma sessão, que é criada no momento em que o MF está prestes a oferecer um chat ao usuário. Para trabalhar com ela, é usado o objeto RoxchatSession.

RoxchatSession

O uso da funcionalidade da biblioteca começa com a criação de um objeto de sessão. O método da classe Roxchat newSessionBuilder() retorna um objeto da classe construtora SessionBuilder (ambas as classes e seus métodos estão descritos no arquivo Roxchat.swift). Em seguida, os métodos são chamados no objeto SessionBuilder criado para definir os parâmetros da sessão. Depois de definir todos os parâmetros necessários, o método build() é executado nesse objeto, que retorna um objeto RoxchatSession.

Exemplo de uso típico:

let roxchatSession =
    try Roxchat.newSessionBuilder().set(accountName: ACCOUNT_NAME).set(location: LOCATION_NAME).build()

Onde ACCOUNT_NAME é o nome de sua conta Roxchat e LOCATION_NAME é o nome do local a ser usado no aplicativo móvel.

Uma descrição de todos os parâmetros que podem ser definidos ao criar uma sessão, bem como os erros que podem ocorrer durante o processo, podem ser encontrados no arquivo Roxchat.swift. Os únicos dois parâmetros obrigatórios são o nome da conta e o local.

Depois que uma sessão é criada, ela deve ser iniciada usando o método resume() (já que o objeto de sessão é criado inicialmente suspenso). Se necessário, a sessão pode ser suspensa (método pause()) e retomada (método resume()), bem como desativada (método destroy()) - todos esses métodos estão descritos no arquivo RoxchatSession.swift.

MessageStream

Todos os métodos referentes ao fluxo de mensagens estão descritos no arquivo MessageStream.swift. Para usar esses métodos, um objeto MessageStream deve ser obtido. Isso é feito pelo método getStream() da instância RoxchatSession.

Exemplos de métodos:

  • send(message:) para enviar uma mensagem,

  • rateOperatorWith(id:,byRating:) - classifica um operador,

  • closeChat() (@available(*, deprecated)) - fecha o chat.

MessageTracker

O método new(messageTracker:) do objeto MessageStream cria um objeto da classe MessageTracker que pode ser usado para controlar o fluxo de mensagens no contexto de um aplicativo cliente. Por exemplo, o método getNextMessages(byLimit:,completion:) solicita um número específico de mensagens do histórico de mensagens.

Uma descrição dos métodos da instância MessageTracker pode ser encontrada no arquivo MessageTracker.swift.

MessageListener

O protocolo MessageListener descreve métodos para rastrear alterações no fluxo de mensagens. Um aplicativo de usuário precisa de uma classe que implemente os métodos desse protocolo: added(message:,after:), removed(message:), removedAllMessages(), changed(message:,to:). Esses métodos são chamados automaticamente quando uma mensagem é adicionada, uma mensagem é excluída, todas as mensagens são excluídas e uma mensagem é modificada, respectivamente.

As descrições completas dos métodos podem ser encontradas no arquivo MessageListener.swift.

Message

Os métodos do protocolo MessageListener operam nos objetos Message descritos no arquivo Message.swift. Usando os métodos das instâncias da classe Message, é possível obter todos os dados necessários sobre uma determinada mensagem: número único da mensagem (método getID()), texto da mensagem (método getText()), informações sobre o arquivo anexado (método getAttachment()) etc.

Todas as ferramentas relacionadas a essa classe (métodos para trabalhar com anexos, tipos de mensagens etc.) também são descritas no arquivo Message.swift.

Recursos adicionais

O arquivo Operator.swift descreve os métodos para obter informações sobre um operador específico. Um objeto de operador específico pode ser recuperado usando o método getCurrentOperator() do objeto MessageStream.

O arquivo RoxchatPushNotification.swift descreve os métodos para lidar com as notificações push recebidas do serviço Rox.Chat. O objeto de uma notificação específica pode ser recuperado usando o método parse(remoteNotification:) da classe Roxchat. A mesma classe também tem o método isRoxchat(remoteNotification:), que permite que você descubra facilmente se uma notificação push foi enviada pelo serviço Rox.Chat ou por algum outro serviço.

O arquivo FatalErrorHandler.swift contém uma descrição do protocolo FatalErrorHandler, cujos métodos podem ser implementados por um aplicativo móvel específico para rastrear erros que ocorrem durante a operação. Todos os erros específicos são descritos no arquivo RoxchatError.swift.

O arquivo MessageStream.swift contém descrições de protocolos adicionais cujos métodos podem ser implementados por classes de aplicativos para rastrear determinados eventos específicos. Por exemplo, os métodos do protocolo ChatStateListener reagem às alterações no estado do chat (as descrições dos possíveis estados do chat estão disponíveis no mesmo arquivo).

Notificações por push

Para ativar as notificações por push, você precisa fornecer certificados APNS para seus aplicativos móveis. Você pode usar um dos conjuntos de certificados ao mesmo tempo: para desenvolvimento (dev) e para produto (dist). Eles podem ser iguais ou diferentes (um certificado para as versões de desenvolvimento e de produto). Cada conjunto consiste em dois arquivos: cert (o certificado propriamente dito) e private_key (a chave privada desse certificado). Também é possível desativar um e outro conjunto de certificados por meio das configurações de account config. Para colocar certificados no servidor Rox.Chat e alterar as definições de account config, entre em contato com nossa equipe de suporte.

Nomes finais dos arquivos de certificado:

ios_push_cert.dev.pem
ios_push_private_key.dev.pem
ios_push_cert.dist.pem
ios_push_private_key.dist.pem

Para processar e exibir automaticamente as notificações push no iOS, seu aplicativo deve estar ciente dos possíveis tipos de notificações e dos argumentos enviados a elas (notificações).

O tipo de notificação por push é definido pelo parâmetro loc-key.

Valores do array de argumentos (parâmetro loc-args):

  • para "P.CR" - a matriz está vazia;

  • para "P.OA" - nome do operador;

  • para "P.OF" - nome do operador, nome do arquivo;

  • para "P.OM" - nome do operador, texto da mensagem;

  • para "P.WM" - a matriz está vazia.

Exemplo de processamento de uma notificação usando o arquivo Strings.localizable:

"P.OM" = "Recebeu uma nova mensagem de %@: %@.".

Conclusão

As entidades descritas acima e seus métodos são tudo o que você precisa para trabalhar em um aplicativo móvel com o serviço Rox.Chat, e ainda mais. Nem todos os recursos dessa biblioteca estão descritos neste guia, portanto, depois de implementar o mínimo necessário em um aplicativo específico, recomenda-se que você se familiarize com a lista completa de protocolos e métodos nos arquivos públicos da biblioteca.

As interfaces, classes e métodos públicos são descritos nos arquivos (em ordem alfabética):

  • FatalErrorHandler.swift

  • Message.swift

  • MessageListener.swift

  • MessageStream.swift

  • MessageTracker.swift

  • Operator.swift

  • ProvidedAuthorizationTokenStateListener.swift

  • Roxchat.swift

  • RoxchatError.swift

  • RoxchatPushNotification.swift

  • RoxchatSession.swift

Uma descrição de cada classe, protocolo, método etc. pode ser encontrada em handbook.

Informações adicionais

O Rox.Chat Mobile SDK usa as bibliotecas SQLite.swift e CryptoSwift.

Não há necessidade de instalar dependências separadas no Podfile.