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

Программные средства разработки (SDK) Pyrus для Android позволяют встроить удобный чат в ваше мобильное приложение. Встроенный чат помогает получать мгновенную обратную связь от пользователей вашего мобильного приложения.

Когда клиент пишет в чат, ваша служба поддержки автоматически получает тикет в Pyrus. Специалист отвечает на заявку прямо в Pyrus, а клиенту приходит пуш-уведомление на телефон и ответ в чат вашего мобильного приложения. Это позволяет специалистам поддержки оперативно решать вопросы клиентов.

Основные возможности

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

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

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

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

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

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

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

repositories {
   mavenCentral()
}

dependencies {
   ...
  implementation 'com.pyrus:servicedesk:1.4.7'

}

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

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

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

Выбрать тип авторизации

Библиотека Pyrus Mobile Chat может работать в одном из двух режимов: с анонимной либо с внешней авторизацией.

Анонимный режим работы требует меньше затрат на внедрение. В этом случае данные чата привязаны к устройству. Пользователь на одном устройстве без использования явных логинов и паролей может писать в чат и видеть ответы операторов.

Основной недостаток анонимного режима в том, что если пользователь использует мобильное приложение на другом устройстве, то предыдущую переписку он не видит.

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

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

Как работает авторизационный сервис

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

1. Пользователь любым способом авторизуется в мобильном приложении и после этого получает от вашего бэкенда пару ( userID, securityKey). На этом этапе библиотека Pyrus Mobile Chat и бэкенд Pyrus не участвуют.

2. При инициализации библиотеки Pyrus Mobile Chat значения userID и securityKey передаются как параметры.

3. В дальнейшем при любом запросе в бэкенд Pyrus (например, при запросе истории переписки или при отправке комментария пользователя) библиотека Pyrus Mobile Chat автоматически передаёт в бэкенд Pyrus параметры (userID, securityKey).

   1. Перед обработкой запроса по существу бэкенд Pyrus проверяет права доступа, для этого передает пару (userID, securityKey) в ваш авторизационный веб-сервис.

   2. Авторизационный веб-сервис в коммуникации с вашим бэкендом проверяют, являются ли параметры (userID, securityKey) подлинными и передают результат проверки обратно в бэкенд Pyrus.

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

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

На открывшейся странице введите URL в соответствующее поле.

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

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

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

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

Данные параметры применяются только при внешней авторизации:

• userID — строка ID пользователя во внешней системе. Не должен меняться у одного и того же пользователя;
• securityKey — строка для аутентификации пользователя user_id во внешней системе. Может меняться у одного и того же пользователя, если внешняя система это позволяет.

Инициализация чата в анонимном режиме:

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

Инициализация чата в режиме внешней авторизации

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

Если передать параметр userId = null, то будет работать анонимная авторизация, привязанная к устройству, а не к пользователю.

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

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

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

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

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

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

Методы класса ServiceDeskConfiguration.Builder

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

Детальная настройка внешнего вида чата

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

Вы можете детально оформить чат с помощью следующих параметров.

• setFont, объект класса String — название шрифта, который используется в чате. Могут использоваться только стандартные шрифты.

• setUserMessageBackgroundColor — тип int, идентификатор ресурса цвета фона для сообщений пользователей.

• setSupportMessageBackgroundColor — тип int, идентификатор ресурса цвета фона для сообщений службы поддержки.

• setUserTextColor — тип int, идентификатор ресурса цвета текста для сообщений пользователя.

• setSupportTextColor — тип int, идентификатор ресурса цвета текста для сообщений службы поддержки.

• setChatTitleColor — тип int, а идентификатор ресурса цвета заголовка чата.

• setToolbarColor — тип int, идентификатор ресурса цвета навигационной панели чата.

• setToolbarButtonColor — тип int, идентификатор ресурса цвета кнопок навигационной панели.

• setBackgroundColor — тип int, идентификатор ресурса цвета фона чата.

• setAttachmentMenuBackgroundColor — тип int, идентификатор ресурса цвета фона меню выбора источника файлов.

• setAttachmentMenuTextColor — тип int, идентификатор ресурса цвета текста в меню с выбором источника файлов.

• setAttachmentMenuButtonColor — тип int, идентификатор ресурса цвета кнопки меню прикрепления файлов.

• setSendButtonColor — тип int, идентификатор ресурса цвета кнопки Отправить.

• setForceDarkAllowed — объект класса boolean, тёмная тема оформления чата. Установка этого параметра в значении true позволить системе автоматически конвертировать цвета в темной теме. Параметр в значении False (установлено по умолчанию) отключает функцию автоматической конвертации.

• setStatusBarColor — тип int, идентификатор цвета строки состояния устройства.

Пример инициализации настроек

Java:

ServiceDeskConfiguration configuration =
    new ServiceDeskConfiguration.Builder()
       .setUserName("Ivan Ivanov")
       .setThemeColor(Color.parseColor("#FF8300"))
       .setChatTitle("Support")
       .setWelcomeMessage("How can I help you?")
       .setAvatarForSupport(R.drawable.psd_download_file)
       .setUserTextColor(R.color.psd_accent)
       .setBackgroundColor(R.color.psd_action_bar_icon_color)
       .setFont("sans-serif-thin")
       .build();

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

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

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

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

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(
        boolean hasUnreadComments,
        @Nullable String lastCommentText,
        int lastCommentAttachmentsCount,
        @Nullable List<String> lastCommentAttachments,
        long utcTime
    ) {
        ...
    }
}

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 — размер файла в байтах.

Чтобы отписаться от push-уведомлений, нужно передать null в функцию setPushToken:

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

Включаем оценку сервиса

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

Чтобы подключить оценку, зайдите в раздел Формы в левом меню и выберите форму, в которой работает Pyrus Mobile Chat.

На странице настройки формы в списке доступных расширений нажмите значок Оценка сервиса.

Установите переключатель в положение Включено.

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

По умолчанию пользователь может отправлять в чат фотографии, сделанные камерой, или выбирать изображения из галереи. Чтобы дать пользователю возможность отправлять другие типы файлов (например, техническую информацию, файлы конфигурации и т. д.), используйте метод 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

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

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

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

public static void registerFileChooser(@Nullable FileChooser fileChooser)

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

public static void start(@NonNull Activity activity)

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

public static void subscribeToReplies(@NonNull NewReplySubscriber subscriber)

public static void unsubscribeFromReplies(@NonNull NewReplySubscriber subscriber)

stop()

OnStopCallback

public interface OnStopCallback

Обратный вызов, который вызывается после остановки работы чата.

ServiceDeskConfiguration.Builder

public class Builder

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

public ServiceDeskConfiguration build()

public Builder setAvatarForSupport(@DrawableRes int drawableResId)

public Builder setChatTitle(@NonNull String title)

public Builder setThemeColor(@ColorInt int color)

public Builder setUserName(@NonNull String userName)

public Builder setWelcomeMessage(@NonNull String message)

Builder setFont(String fontName)

Builder setUserMessageBackgroundColor(@ColorRes int color)

Builder setSupportMessageBackgroundColor(@ColorRes int color)

Builder setUserTextColor(@ColorRes int color)

Builder setSupportTextColor(@ColorRes int color)

Builder setChatTitleColor(@ColorRes int color)

Builder setToolbarColor(@ColorRes int color)

Builder setToolbarButtonColor(@ColorRes int color)

Builder setBackgroundColor(@ColorRes int color)

Builder setAttachmentMenuBackgroundColor(@ColorRes int color)

Builder setAttachmentMenuTextColor(@ColorRes int color)

Builder setAttachmentMenuButtonColor(@ColorRes int color)

Builder setForceDarkAllowed(boolean forceDarkAllowed)

Builder setStatusBarColor(@ColorRes int color)

NewReplySubscriber

public interface NewReplySubscriber

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

void onNewReply(
        boolean hasUnreadComments,
        @Nullable String lastCommentText,
        int lastCommentAttachmentsCount,
        @Nullable List<String> lastCommentAttachments,
        long utcTime
)

FileChooser

public interface FileChooser

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

Intent getIntent()

String getLabel()

SetPushTokenCallback

public interface SetPushTokenCallback

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

public void onResult(@Nullable Exception exception)

Авторизационный веб-сервис

Получает вызов HTTP POST c параметрами:

• app_id: строка, создается Pyrus в настройках мобильного чата;
• user_id: строка до 100 символов, ID пользователя во внешней системе. Никогда не должен меняться. Не может совпадать у разных пользователей, в том числе бывших;
• security_key: строка до 100 символов, для аутентификации пользователя user_id во внешней системе. Логика формирования и использования security_key полностью отдается на ваше усмотрение. Не рекомендуем использовать без хеширования с солью пароли, секретные ключи и другие параметры, которые позволяют авторизоваться в мобильном приложении или дают доступ к каким-либо другим вашим системам.

Ожидаемый ответ:

• в случае успешной авторизации: HTTP 200 OK;
• в случае некорректно сформированного запроса (неправильные поля либо security_key неверного для вашей системы формата): HTTP 400 Bad Request;
• в случае неуспешной авторизации: HTTP 403 Forbidden.

The authorization web service

Receives the command HTTP POST with the parameters:

• app_id: this line is created in Pyrus in the mobile chat settings;
• user_id: this line of up to 100 symbols is the user ID in the external system. This value must never change, and cannot be the same for different users, including former ones;
• security_key: this line of up to 100 symbols is for authenticating the user’s user_id in the external system. In this mode, the logic of the formation and use of the security_key is entirely up to you. We do not recommend using this mode without hash coding the passwords, secret keys, and other parameters that grant users access to any of your systems, or to get authorized on a mobile app.

The expected response:

• if authorization is successful: HTTP 200 OK;
• if the request was formed incorrectly (the wrong fields were filled in, or the security_key is in the wrong format for your system): HTTP 400 Bad Request;
• if authorization fails: HTTP 403 Forbidden.