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

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

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

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

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

1. Включите интеграцию в Pyrus. Убедитесь, что администратор формы в Pyrus включил интеграцию с чатом в приложении.
2. Получите 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).

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

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

3.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.

• 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 lastCommentAttachments,
        long utcTime
    ) {
        ...
    }
}

Вы можете настроить отправку 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);
           }
       });
   }
}

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

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, описывающих внешний вид чата.

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

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

setFont

Builder setFont(String fontName)

Задаёт тип шрифта, который используется в чате.

setUserMessageBackgroundColor

Builder setUserMessageBackgroundColor(@ColorRes int color)

Задаёт цвет фона для сообщений пользователей.

setSupportMessageBackgroundColor

 Builder setSupportMessageBackgroundColor(@ColorRes int color)

Задаёт цвет фона для сообщений службы поддержки.

setUserTextColor

Builder setUserTextColor(@ColorRes int color)

Задаёт цвет текста для сообщений пользователя.

setSupportTextColor

 Builder setSupportTextColor(@ColorRes int color) 

Задаёт цвет текста для сообщений службы поддержки.

setChatTitleColor

 Builder setChatTitleColor(@ColorRes int color)

Задаёт цвет заголовка чата.

setToolbarColor

Builder setToolbarColor(@ColorRes int color)

Задаёт цвет навигационной панели чата.

setToolbarButtonColor

 Builder setToolbarButtonColor(@ColorRes int color)

Задаёт цвет кнопок навигационной панели.

setBackgroundColor

 Builder setBackgroundColor(@ColorRes int color)

Задаёт цвет фона чата.

setAttachmentMenuBackgroundColor

 Builder setAttachmentMenuBackgroundColor(@ColorRes int color)

Задаёт цвета фона меню выбора файлов.

setAttachmentMenuTextColor

 Builder setAttachmentMenuTextColor(@ColorRes int color)

Задаёт цвет текста в меню с выбором источника файлов.

setAttachmentMenuButtonColor

Builder setAttachmentMenuButtonColor(@ColorRes int color)

Задаёт цвет кнопки меню прикрепления файлов.

setForceDarkAllowed

 Builder setForceDarkAllowed(boolean forceDarkAllowed)

Задаёт значение флага, позволяющего системе Android автоматически конвертировать цвета в темной теме.

setStatusBarColor

Builder setStatusBarColor(@ColorRes int color)

Задаёт значение флага, позволяющего системе Android автоматически конвертировать цвета в темной теме.

NewReplySubscriber

public interface NewReplySubscriber

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

FileChooser

public interface FileChooser

Intent getIntent()

String getLabel()

SetPushTokenCallback

public interface SetPushTokenCallback

public void onResult(@Nullable Exception exception)

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

The authorization web service