mobile:in-app-chat-android

Встраиваемый чат для мобильных приложений Android

Встраиваемый чат для Android поможет решить две задачи:

  • клиенты смогут обратиться в поддержку напрямую из приложения и оперативно решить свой вопрос,
  • специалисты поддержки будут обрабатывать такие обращения в Pyrus аналогично заявкам из других источников.

Вы можете использовать внешний вид чата по умолчанию или настроить его так, чтобы он выглядел как органичная часть вашего приложения. Также мы предусмотрели возможность отправки файлов в чат и подписку на уведомления о новых сообщениях.

Эта инструкция поможет разработчикам шаг за шагом встроить чат в приложение.

Получить идентификатор приложения (AppID)

Чтобы специалисты службы поддержки могли обрабатывать сообщения из чата в Pyrus, ваше приложение нужно подключить к форме, в которой ведётся работа с обращениями клиентов. Для начала работы вам понадобится аккаунт администратора в Pyrus с доступом к настройке формы, в которой обрабатываются обращения пользователей. Если у вас нет такого аккаунта, обратитесь к коллеге, у которого он есть.

  1. Включите интеграцию в Pyrus. Убедитесь, что администратор формы в Pyrus включил интеграцию с чатом в приложении.
  2. Получите AppID в настройке формы в Pyrus. Мы сгенерируем его автоматически, когда администратор формы включит интеграцию. AppID записан на странице настройки интеграции.

Подготовить проект

В файл build.gradle добавьте:

repositories {
   jcenter()
}

dependencies {
   ...
   implementation 'com.pyrus:servicedesk:1.1.2'
}

Запросить разрешение на доступ к камере и галерее

Чтобы пользователи могли прикреплять к сообщениям фотографии из галереи на устройстве или сфотографировать что-то, модуль запрашивает соответствующие доступы.

"android.permission.WRITE_EXTERNAL_STORAGE"
"android.permission.CAMERA"

Инициализировать библиотеку

При старте приложения вызовите метод init() класса PyrusServiceDesk.

Параметры метода init():

  • application — объект класса Application, используемый вашим приложением.
  • appId — идентификатор вашего приложения в Pyrus. Он записан в настройке формы, к которой подключён чат. Если у вас нет доступа, попросите администратора формы скопировать AppID, как описано в разделе «Получить идентификатор приложения (AppID)».

public class SampleApp extends Application {
   @Override
   public void onCreate() {
       super.onCreate();
       PyrusServiceDesk.init(
               application: this,
               appId: "your_app_id"
       );
   }
}

Запустить пользовательский интерфейс чата

Чтобы запустить пользовательский интерфейс, вызовите метод start() класса PyrusServiceDesk:

Метод start(activity) запускает пользовательский интерфейс с конфигурацией по умолчанию:

  • activity — объект класса Activity. Нужен для запуска пользовательского интерфейса.

Чтобы настроить внешний вид чата, используйте метод start(activity, configuration):

  • activity — объект класса Activity. Нужен для запуска пользовательского интерфейса.
  • configuration — объект класса ServiceDeskConfiguration. Используется для настройки оформления чата.

public class SampleActivity extends Activity{
   @Override
   protected void onCreate(Bundle savedInstanceState) {
	...
       findViewById(R.id.support).setOnClickListener(
               view -> PyrusServiceDesk.start(
				/* activity */this,
				/* configuration */
                      serviceDeskConfigurationInstance
       );
   }
}

Настроить оформление чата

Для запуска пользовательского интерфейса используйте метод start(activity, configuration). Создать и настроить объект ServiceDeskConfiguration можно с помощью объекта класса ServiceDeskConfiguration.Builder.

Методы объекта ServiceDeskConfiguration.Builder:

  • setUserName(name) задаёт имя пользователя (клиента поддержки), которое специалист службы поддержки увидит в Pyrus. Если пользователь авторизовался в приложении, вы можете передавать имя, почту и другие его данные в этот метод, чтобы оператор поддержки понимал, с кем общается, и быстрее решил вопрос.
  • setChatTitle(title) задаёт заголовок в окне чата с поддержкой.
  • setWelcomeMessage(message) задаёт приветственное сообщение, которое по умолчанию отображается первым в чате.
  • setThemeColor(color) задаёт цвет основных элементов интерфейса.
  • setAvatarForSupport(drawableResID) задаёт иконку, которая используется как аватар сотрудника службы поддержки. drawableResID — идентификатор ресурса, используемого в качестве аватара.
  • build() создает объект класса ServiceDeskConfiguration.

new ServiceDeskConfiguration.Builder()
.setUserName("Иван Петров")
       .setChatTitle("Поддержка ИмяОрганизации")
       .setWelcomeMessage("Добрый день! Как я могу вам помочь?")
       .setThemeColor(Color.RED)
       .setAvatarForSupport(R.drawable.logo)
       .build())

Уведомления о новом сообщении в чате

Вы можете настроить отправку push-уведомлений, чтобы оповещать пользователя о новых сообщениях в чате. В этом разделе описан альтернативный вариант. Он проще в реализации, но уведомления будут приходить с задержкой и вы не увидите содержимое нового комментария. Настроить push-уведомления

Чтобы получать уведомления о новых сообщениях от сотрудника поддержки в чате, реализуйте интерфейс NewReplySubscriber и передайте реализацию интерфейса в метод subscribeToReplies() класса PyrusServiceDesk.

public class SampleActivity extends Activity implements NewReplySubscriber {
   @Override
   protected void onCreate(Bundle savedInstanceState) {
	  ...
       PyrusServiceDesk.subscribeToReplies(this);
	  ...
    }
@Override
protected void onDestroy() {
   ...
   PyrusServiceDesk.unsubscribeFromReplies(this);
   ...
}
   @Override
   public void onNewReply() {
       textView.setText("Есть непрочитанные сообщения");
   }
}

Push-уведомления

Вы можете настроить отправку push-уведомлений, чтобы пользователь узнавал, когда специалист поддержки отправит комментарий в чат. Общая схема оповещения выглядит так: специалист отвечает на обращение клиента в Pyrus, из Pyrus с помощью вебхука ответ специалиста и push-токен отправляется на ваш сервер. Затем push-сервер Google отправляет в приложение клиента push-уведомление о новом сообщении в чате.

Чтобы это работало, push-сервер Google должен знать токен, уникальный для устройства и вашего приложения. При запуске ваше приложение связывается с push-сервером Google и получает токен устройства, который записывается в Pyrus.

Чтобы подписаться на уведомления, зарегистрируйте пуш-токен с помощью вызова setPushToken(token, callback) класса PyrusServiceDesk.

Параметры метода setPushToken(token, callback):

  • token — токен, который регистрируется в Pyrus. Используется для отправки push-уведомлений о новом сообщении в чате.
  • callback — реализация интерфейса SetPushTokenCallback, метод onResult() которого будет вызван при завершении регистрации токена. Не гарантируется, что метод onResult() будет вызван в том же потоке, в котором был вызван setPushToken(token, callback).

SetPushTokenCallback имеет метод onResult(@Nullable Exception exception), параметр exception которого при успешной регистрации будет null, в противном случае exception будет содержать сообщение об ошибке.

Пример:

public class SampleApp extends Application {

   @Override
   public void onCreate() {
       super.onCreate();
       PyrusServiceDesk.init(
               this,
               "my_app_id"
       );

       PyrusServiceDesk.setPushToken(
               "my_push_token",
               exception -> {
                   Log.d("SAMPLE_APP", exception.getMessage());
               });

   }
}

На стороне сервера приложения нужно реализовать вебхук, который будет получать уведомления о новых комментариях в чате. И в настройке формы добавьте его URL.

При появлении нового ответа от поддержки на этот URL будет отправляться POST-запрос со следующим содержанием:

ticket_id — номер задачи, в которую добавлен комментарий.

token — идентификатор пользователя, включающий:

  • user_id — идентификатор пользователя, который передается при каждом запросе;
  • app_id — идентификатор мобильного приложения/веб-чата;
  • device_id — идентификатор устройства;
  • type — тип устройства: «Android».

comment — информация о новом комментарии:

  • comment_id — номер нового комментария;
  • body — текст комментария;
  • is_inbound — всегда false, показывает, что комментарий исходящий, то есть ответ поддержки.

author — информация об авторе комментария:

  • name — имя автора;
  • avatar_id — идентификатор аватара автора;
  • avatar_color — цвет аватара автора. Используется, если avatar_id не заполнено.

created_at — дата и время создания комментария.

attachments — описание приложенных файлов:

  • id — идентификатор файла;
  • name — имя файла;
  • size — размер файла в байтах.

Настройка меню отправки файлов в чат

По умолчанию пользователь может отправлять в чат фотографии, сделанные камерой, или выбирать изображения из галереи. Чтобы дать пользователю возможность отправлять другие типы файлов (например, техническую информацию, файлы конфигурации и т. д.), используйте метод registerFileChooser() класса PyrusServiceDesk.

PyrusServiceDesk.registerFileChooser(chooser), где chooser — реализация интерфейса FileChooser. Для того, чтобы перестать использовать настроенный FileChooser, в метод нужно передать null.

Методы FileChooser:

  • getLabel() — заголовок пункта в меню выбора файлов.
  • getIntent() — возвращает объект типа Intent, который будет использован для запуска activity, от которого ожидается получить результат. Пользовательское activity, которое будет вызвано с помощью intent, должно вернуть результат, содержащий Uri для доступа к файлу (добавьте Uri в результат методом intent.setData(uri)).

Важно: схема отправляемого Uri должна быть «content», в противном случае комментарий с файлом добавлен не будет.

public class SampleApp extends Application {
   @Override
   public void onCreate() {
       ...      
       PyrusServiceDesk.registerFileChooser(new FileChooser() {
           @NonNull
           @Override
           public String getLabel() {
               return "Отправить логи";
           }
           @NonNull
           @Override
           public Intent getIntent() {
               return new Intent(SampleApp.this, LogChooser.class);
           }
       });
   }
}

Описание используемых типов и методов

PyrusServiceDesk

Главный класс для работы со встраиваемым чатом поддержки.

init

public static void init(@NonNull Application application, @NonNull String appId)

Метод инициализирует встраиваемый модуль Pyrus Service Desk. Лучше всего вызывать метод в [Application.onCreate].

Примечание: это нужно сделать до вызова других публичных методов, в противном случае будет возникать IllegalStateException.

Параметры

appId Идентификатор приложения в Pyrus.
application Приложение, в которое встраивается модуль.

registerFileChooser

public static void registerFileChooser(@Nullable FileChooser fileChooser)

Задаёт источник, который будет добавлен в меню для выбора. Пользователь может воспользоваться им, чтобы прикрепить файл к сообщению в чат. Прикрепить можно файлы, размер которых не превышает [RequestUtils.MAX_FILE_SIZE_MEGABYTES]. Сейчас максимальный размер загружаемого файла — 250 Мб.

Параметры

fileChooser Запускает интерфейс для выбора файлов. Для отключения можно передавать null.

setPushToken

public static void setPushToken(@NonNull String token, @NonNull SetPushTokenCallback callback)

Регистрирует push-токен. Обратный вызов [callback] может быть вызван в потоке, который отличается от того, в котором был вызван [setPushToken].

Параметры

callback Обратный вызов, который вызывается, когда завершена регистрация токена. Если токен успешно зарегистрирован, вызов происходит без ошибок.
token Токен для регистрации.

start

public static void start(@NonNull Activity activity)

Запускает интерфейс PyrusServiceDesk в стандартной конфигурации.

Параметры

activity Запускает интерфейс PyrusServiceDesk в настроенной конфигурации.

start

 public static void start(@NonNull Activity activity, @NonNull ServiceDeskConfiguration configuration)

Запускает интерфейс PyrusServiceDesk.

Параметры

activity Запускает интерфейс PyrusServiceDesk.
configuration Сущность [ServiceDeskConfiguration], которая используется для настройки интерфейса.

subscribeToReplies

public static void subscribeToReplies(@NonNull NewReplySubscriber subscriber)

Подписывает [subscriber] на уведомления о том, что в чате появились новые сообщения от поддержки.

unsubscribeFromReplies

public static void unsubscribeFromReplies(@NonNull NewReplySubscriber subscriber)

Отписывает [subscriber] от оповещений о новых сообщениях от поддержки в чате.

ServiceDeskConfiguration.Builder

public class Builder

Конструктор для создания пользовательского чата [ServiceDeskConfiguration].

build

public ServiceDeskConfiguration build()

Создаёт объект типа [ServiceDeskConfiguration].

setAvatarForSupport

public Builder setAvatarForSupport(@DrawableRes int drawableResId)

Задаёт идентификатор ресурса с изображением, которое используется в качестве аватара специалиста службы поддержки. По умолчанию используется стандартная иконка, в качестве фона — цвет, который был настроен при вызове метода PyrusServiceDesk.start(). Если цвет на задан или не настроен, цвет фона — #008C8C.

Параметры

ID Идентификатор изображения.

setChatTitle

public Builder setChatTitle(@NonNull String title)

Содержит текст для заголовка чата. По умолчанию используется «Поддержка» или "Support" в зависимости от локали.

Параметры

title Отображаемый заголовок чата.

setThemeColor

public Builder setThemeColor(@ColorInt int color)

Устанавливает цвет основных элементов чата. По умолчанию: #008C8C.

Параметры

color Цвет основных элементов чата.

setUserName

public Builder setUserName(@NonNull String userName)

Задаёт имя пользователя (клиента поддержки), которое специалист службы поддержки увидит в Pyrus. По умолчанию используется «Гость» или "Guest" в зависимости от локали. Если пользователь авторизовался в приложении, вы можете передавать имя, почту и другие его данные в этот метод, чтобы оператор поддержки понимал, с кем общается, и быстрее решил вопрос.

Параметры

userName Имя пользователя.

setWelcomeMessage

public Builder setWelcomeMessage(@NonNull String message)

Задаёт текст для приветственного сообщения, которое пользователь увидит в чате, когда откроет его. Если текст не задан, чат будет отображаться без приветственного сообщения.

Параметры

message Приветственное сообщение.

NewReplySubscriber

public interface NewReplySubscriber

Реализация интерфейса может быть подписана на уведомления о новых сообщениях от поддержки с помощью метода subscribeToReplies() класса PyrusServiceDesk.

onNewReply

void onNewReply()

Вызывается при получении нового ответа от поддержки.

FileChooser

public interface FileChooser

Чтобы появилась возможность прикреплять файлы к сообщениям в чат, нужно реализовать интерфейс для передачи в [PyrusServiceDesk.registerFileChooser].

getIntent

Intent getIntent()

Используется для запуска настроенного меню выбора файла, когда пользователь кликает на вариант с текстом, который содержится в[getLabel].

getLabel

String getLabel()

Текст, который отображается в меню для выбора источника файла.

SetPushTokenCallback

public interface SetPushTokenCallback

Обратный вызов, который вызывается когда регистрация push-токена завершена. Возврат без исключения означает, что токен успешно зарегистрирован.

onResult

public void onResult(@Nullable Exception exception)

Метод, который вызывается, когда регистрация push-токена завершена.

Была ли эта статья полезной?

Да, спасибо! Нет, остался вопрос