Ir para o conteúdo

Integração em aplicativos móveis Android

Este artigo fornece instruções detalhadas sobre como integrar o Rox.Chat Mobile SDK em seu aplicativo Android.

Etapa 1: instalar a biblioteca do Rox.Chat Mobile SDK

  1. Abra o arquivo build.gradle do aplicativo (módulo). Especifique o endereço do repositório e adicione o seguinte código:

    repositórios {
    mavenCentral()
}

dependências {
    ...
    implementação 'com.roxchat.sdk:roxclientsdkandroid:3.+'
}

    Para que as alterações sejam aplicadas, você precisa sincronizar o projeto. Por exemplo, no Android Studio, você pode clicar em Sync Now ou selecionar File → Sync Progect with Gradle Files no menu. Aguarde a conclusão da sincronização.

    Se a sincronização for bem-sucedida, a biblioteca será adicionada ao projeto automaticamente durante a compilação. Se a compilação falhar, verifique se você especificou o repositório e a dependência corretos e sincronize o projeto novamente.

  2. Edite o arquivo AndroidManifest.xml. Você precisa adicionar os seguintes itens ao seu manifesto: Na raiz do manifest, você precisa adicionar a permissão:

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

    As seguintes dependências devem ser adicionadas para armazenar o histórico de bate-papo em seu dispositivo:

    <uses -permission android:name="android.permission.READ_EXTERNAL_STORAGE">
<uses -permission android:name="android.permission.WRITE_EXTERNAL_STORAGE">

    Se for necessário evitar que o dispositivo entre em modo de suspensão para receber sempre mensagens do bate-papo, a seguinte linha será adicionada:

    <uses -permission android:name="android.permission.WAKE_LOCK">

Etapa 2. Trabalhar com o Rox.Chat Mobile SDK

Trabalhar com a sessão

Depois de implementar a dependência no aplicativo, você precisa criar uma sessão. Uma sessão no Rox.Chat Mobile SDK é uma entidade separada da VisitSession, que é implementada no Rox.Chat Server.

Uma sessão é uma sessão durante a qual um aplicativo interage com um serviço. Na versão atual do SDK, ele recebe qualquer informação do Rox.Chat Server somente dentro de uma sessão. Antes de sua criação, o SDK não receberá nenhuma informação do servidor. A sessão é iniciada com a execução do método resume() e encerrada com a execução do método destroy() ou com o encerramento do aplicativo.

Mas, para começar a executar ações em uma sessão, você deve primeiro criar um objeto de sessão.

  1. Criação de uma sessão. O objeto de sessão é criado pelo método newSessionBuilder da classe Rox, que retorna um objeto da classe construtora SessionBuilder (ambas as classes e seus métodos estão descritos no arquivo Rox.java). Depois de definir todos os parâmetros necessários no objeto SessionBuilder criado, o método build() é chamado, o que retorna um objeto RoxSession. Exemplo de uso (para Android):

    RoxSession roxChatSession = Rox.newSessionBuilder()
    .setAccountName(ACCOUNT_NAME)
    .setLocation(LOCATION_NAME)
    .build()

    O campo ACCOUNT_NAME deve corresponder ao nome da conta se o chat estiver hospedado em uma configuração de nuvem (em servidores Rox.Chat - consulte Configurações de rede do serviço Rox). Se o chat estiver hospedado nos servidores do cliente, a URL completa deverá ser especificada em vez disso (exemplo: https://chat.company.ru).

    O campo LOCATION_NAME contém o nome do posicionamento. Se você especificar um valor inexistente nesse campo, a invocação será feita no posicionamento default.

    A chamada do método build() conclui a configuração dos parâmetros iniciais e cria a sessão em formato suspenso.

    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 em [reference] (android-sdk-handbook.md#session-builder). Apenas dois deles são obrigatórios: nome da conta e posicionamento.

    Se apenas o nome da conta e o local forem definidos, a sessão será criada em uma área não autorizada, mas será um bate-papo pessoal.

  2. Métodos de sessão. Abaixo estão os métodos básicos que precisam ser salvos ao trabalhar com um objeto de sessão.

    | Método | Descrição | Próximo método | Método | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Depois que o objeto de sessão é criado, o método resume() deve ser chamado para iniciar a sessão. As a result of the server response, the session's network activity is started as a result of which the MessageListener, ChatStateListener, CurrentOperatorChangeListener and LocationSettingsChangeListener methods may be called. This method is also used to resume a session after calling the pause() method. | pause()
    destroy()
    destroyWithClearVisitorData() | | pause() | A method that is used to suspend the network activity of a session (for example, when the user is not in an active application window). If the session is already in a suspended state, the method will not perform any action. | resume()
    destroy()
    destroyWithClearVisitorData() | | destroy() | A method that is used to deactivate the session and class instance. | No session related methods can be used after calling this method. | | destroyWithClearVisitorData() | A method that is used to deactivate the session and class instance with the user information removed. | Nenhum método relacionado à sessão pode ser usado após a chamada desse método. |

    Exemplos de uso:

    public class MainActivity extends AppCompatActivity {
  private RoxSession session;
  private static final String ACCOUNT_NAME = "conta";
  private static final String LOCATION_NAME = "mobile";
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
      roxChatSession = Rox.newSessionBuilder()
          .setAccountName(ACCOUNT_NAME)
          .setLocation(LOCATION_NAME)
          .build()
  }
  protected void onStart() {
      super.onStart();
      session.resume();
  }
  protected void onResume() {
      super.onResume();
      session.resume();
  }
  protected void onPause() {
      super.onPause();
      session.pause();
  }
  protected void onDestroy() {
      session.destroy();
      super.onDestroy();
  }
}

Instalação de interfaces e protocolos

Todas as interfaces e protocolos a seguir devem ser instalados para que um aplicativo baseado em SDK funcione. Para usar os métodos de interface, é necessário que a sessão não esteja em estado suspenso ou desativado.

  1. O MessageStream é necessário para a interação direta com o serviço Rox.Chat (por exemplo, para enviar ou receber mensagens). Ele é definido chamando o método getStream() da instância RoxSession. Exemplos de uso:

    • Enviar uma mensagem

      session.getStream().sendMessage(message);

    • Excluir mensagem

      session.getStream().deleteMessage(message, callback);

    • Rastrear alterações no operador de chat atual

      session.getStream().setCurrentOperatorChangeListener(
        novo MessageStream.CurrentOperatorChangeListener() {
        @Override
        public void onOperatorChanged(@Nullable Operator oldOperator,
                                @Nullable Operator newOperator) {
//seu código
       }
   });

    • Rastrear alterações no status da sessão

      session.getStream().setVisitSessionStateListener(
        novo MessageStream.VisitSessionStateListener() {
        @Override
        public void onStateChange(@NonNull MessageStream.VisitSessionState previousState,
                                @NonNull MessageStream.VisitSessionState newState) {
//seu código
        }
    });

    • Rastreie as alterações no estado atual do chat

      session.getStream().setChatStateListener(
        novo MessageStream.ChatStateListener() {
        @Override
        public void onStateChange(@NonNull MessageStream.ChatState oldState,
                                @NonNull MessageStream.ChatState newState) {
//seu código
        }
    });

    A lista de todos os métodos, bem como informações mais detalhadas sobre eles, pode ser encontrada na descrição do método [MessageStream] (android-sdk-handbook.md#message-stream).

  2. O MessageListener é necessário para receber alterações no fluxo de mensagens. Seus métodos são chamados automaticamente ao executar ações em mensagens na sala de bate-papo: ao adicionar uma mensagem, excluir uma mensagem, excluir todas as mensagens e modificar uma mensagem, respectivamente. Em um aplicativo de usuário, você precisa de uma classe que implemente os métodos dessa interface: messageAdded(Message, Message), messageRemoved(Message), allMessagesRemoved(), messageChanged(Message, Message).

    Exemplo de uso:

    public class MainActivity extends AppCompatActivity {
    private RoxSession session;
    ListController listController privado;
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        roxChatSession = Rox.newSessionBuilder()
            .setAccountName(ACCOUNT_NAME)
            .setLocation(LOCATION_NAME)
            .build()
        initChatView(rootView);
    }
    private void initChatView(View rootView) {
      RecyclerView recyclerView = rootView.findViewById(R.id.chat_recycler_view);
        listController = ListController.install(this, recyclerView);
    }
    private static class ListController implements MessageListener {
        private static final int MESSAGES_PER_REQUEST = 25;
        private final RecyclerView recyclerView;
        adaptador final privado MessagesAdapter;
        static ListController install(RoxChatFragment roxChatChatFragment,
                                      RecyclerView recyclerView) {
            return new ListController(roxChatChatFragment, recyclerView);
        }
        private ListController(final RoxChatFragment roxChatChatFragment,
                               final RecyclerView recyclerView) {
            this.recyclerView = recyclerView;
            this.adapter = new MessagesAdapter(roxChatChatFragment);
            this.recyclerView.setAdapter(this.adapter);
        }
        @Override
        public void messageAdded(@Nullable Message before, @NonNull Message message) {
            int index = (before == null) ? 0 : adapter.indexOf(before);
            Se (index < = 0) {
                adapter.add(message);
                adapter.notifyItemInserted(0);
            } else {
                adapter.add(index, message);
                adapter.notifyItemInserted(adapter.getItemCount() - index - 1);
            }
        }

        @Override
        public void messageRemoved(@NonNull Message message) {
            int index = adapter.indexOf(message);
            se (index != -1) {
                adapter.remove(index);
                adapter.notifyItemRemoved(adapter.getItemCount() - index);
            }
        }

        @Override
        public void messageChanged(@NonNull Message from, @NonNull Message to) {
            int index = adapter.lastIndexOf(from);
            se (index != -1) {
                adapter.set(index, to);
                adapter.notifyItemChanged(adapter.getItemCount() - index - 1, 42);
            }
        }

        @Override
        public void allMessagesRemoved() {
            int size = adapter.getItemCount();
            adapter.clear();
            adapter.notifyItemRangeRemoved(0, size);
        }
    }
}

    Uma lista de todos os métodos, bem como informações completas sobre eles, pode ser encontrada na descrição de [MessageListener] (android-sdk-handbook.md#message-listener).

    1. O MessageTracker é necessário para recuperar o histórico de mensagens, que é armazenado no dispositivo local. No servidor, o histórico de mensagens é armazenado sem limitação de tempo. O objeto da classe MessageTracker pode ser recuperado por meio do método newMessageTracker(MessageListener) do objeto MessageStream:

      MessageTracker tracker = session.getStream.newMessageTracker(this);

      O método newMessageTracker(MessageListener) 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. Você pode usar o método getLastMessages(int limit, GetMessagesCallback callback) para recuperar as mensagens mais recentes do histórico, mas não mais do que o limite especificado.

      Exemplo de uso do método:

      int MESSAGES_PER_REQUEST = 25;
tracker.getLastMessages(MESSAGES_PER_REQUEST, new MessageTracker.GetMessagesCallback() {
                @Override
                public void receive(@NonNull final List< ? extends Message> received) {
                    //seu código
                }
            });

      Para iterar ainda mais o histórico de mensagens, o método getNextMessages(int limit, GetMessagesCallback) é chamado - ele solicita um determinado número de mensagens do histórico.

      Exemplo de uso do método:

      int MESSAGES_PER_REQUEST = 25;
tracker.getNextMessages(MESSAGES_PER_REQUEST, new MessageTracker.GetMessagesCallback() {
                @Override
                public void receive(@NonNull final List< ? extends Message> received) {
                    //seu código
                }
            });

      A classe Message é necessária para armazenar informações sobre mensagens. 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. Os métodos da interface MessageListener operam em objetos da classe Message. Todas as ferramentas relacionadas a essa classe (métodos para trabalhar com anexos, tipos de mensagens etc.) estão descritas [aqui] (android-sdk-handbook.md#message).

      A descrição detalhada desses e de outros métodos pode ser encontrada nos guias de métodos para iOS e Android.

    Etapa 3: Outras configurações

    Além de instalar as interfaces listadas acima, para a operação correta do aplicativo com base no Rox.Chat Mobile SDK, você precisa fazer várias configurações no código do aplicativo.

    1. É necessário configurar corretamente os campos de visitantes e o procedimento de contagem de hash. A chave privada da conta não deve ser armazenada no dispositivo ou em qualquer outro lugar que não seja o servidor do cliente. Caso contrário, haverá uma séria ameaça à segurança e o risco de vazamento da correspondência do cliente para terceiros.

      Exemplo de transmissão do objeto json-encoded de um visitante do SDK:

      .setVisitorFieldsJson("{
    "id":"1234567890987654321",
    "display_name": "Nikita",
    "hash":"ffadeb6aa3c788200824e311b9aa44cb"
}")
      1. Um ofuscador pode ser usado para um aplicativo baseado em SDK. Nesse caso, é necessário definir exceções nas regras do ofuscador para que determinadas classes não sejam ofuscadas - isso é necessário para o funcionamento correto do aplicativo baseado no Rox.Chat Mobile SDK. Em particular, ao usar o ofuscador Proguard, você deve definir o seguinte em suas regras:
-keep public class com.roxchat.android.sdk.* { *; }

Isso significa que o pacote/classe especificado não será "criptografado" pelo ofuscador.

  1. Forneça os acessos de rede necessários.

Para um dispositivo móvel que executa um aplicativo móvel integrado com o Rox.Chat Mobile SDK, as portas de saída devem estar abertas para os seguintes URLs:

* `https://*.rox.chat/l/v/m/action 443 (POST)` - usado para transmitir ações de clientes.

* `https://*.rox.chat/l/v/m/delta 443 (GET)` - usado para receber atualizações incrementais.

* `https://*.rox.chat/l/v/m/download 443 (GET)` (não usado no SDK, mas necessário para baixar arquivos no aplicativo móvel)

* `https://*.rox.chat/l/v/m/upload 443 (POST)` - usado para enviar arquivos do cliente para o servidor.

* `https://*.rox.chat/l/v/m/history 443 (GET)` - usado para obter o histórico de bate-papo do banco de dados.

As seguintes portas devem estar abertas para enviar notificações push:

* FCM: `5228-5230 TCP`, consulte <https://firebase.google.com/docs/cloud-messaging/concept-options>.

* APNs: `443, 2197, 5223 TCP`, consulte <https://support.apple.com/en-us/HT203609>.

Se o bate-papo estiver hospedado nos servidores do cliente, o domínio deverá ser alterado para o seu próprio.

  1. Para permitir que o usuário avalie o desempenho do operador após o término do chat, é necessário descrever o mecanismo correspondente no aplicativo. O SDK não implementa o mecanismo de avaliação, mas o obtém do aplicativo cliente.

  2. As notificações por push estão ativadas e configuradas (opcional).

  3. O método startChat() pode ser chamado para iniciar um chat. Se o método não for chamado, o chat será iniciado após a primeira mensagem do visitante.