Сбор отзывов пользователей в библиотеке пользовательского интерфейса ACS

Для включения обратной связи пользователей в библиотеке пользовательского интерфейса Служб коммуникации Azure (ACS) разработчикам необходимо предпринять действия. Используя onUserReportedIssueEventHandler интеграцию библиотеки, разработчики могут включить встроенную форму поддержки, позволяя пользователям сообщать о проблемах напрямую. В этом разделе описано, как настроить форму обратной связи на стороне клиента.

Реализация сбора отзывов на стороне клиента в Android

Включение формы поддержки

1. Регистрация обработчика событий:

   • Чтобы активировать форму поддержки в приложении Android, зарегистрируйте onUserReportedIssueEventHandler ее в соответствующей точке жизненного цикла приложения. Эта регистрация включает не только форму, но и гарантирует, что она становится видимой и доступной для пользователей.

2. Видимость форм и доступность:

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

Запись и обработка событий поддержки

1. Генерация событий при отчетах о проблемах:

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

2. Подготовка данных к отправке:

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

Отправка данных о проблеме на сервер

1. Асинхронная передача данных:

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

2. Обработка ответов сервера:

   • При отправке данных крайне важно умело обрабатывать ответы сервера. Эта обработка может включать анализ отзывов сервера, чтобы подтвердить успешную передачу данных и, возможно, извлечь ссылку на отправленную проблему (например, номер билета или URL-адрес), которую можно передать пользователю.

Предоставление отзывов пользователей и уведомлений

1. Немедленная обратная связь пользователей:

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

2. Стратегия уведомлений для Android O и более поздних версий:

   • Для устройств под управлением Android O (уровень API 26) и более новых версий необходимо реализовать канал уведомлений, специфичный для отправки отчетов. Эта настройка необходима для эффективной доставки уведомлений и является обязательным требованием для этих версий Android.

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

Пример кода Android

Фрагмент кода Kotlin демонстрирует процесс интеграции системы для обработки пользовательских проблем в приложении Android с помощью Служб коммуникации Azure. Эта интеграция направлена на упрощение процесса поддержки путем прямого взаимодействия между пользователями и группами поддержки. Ниже приведен обзор описанных действий.

1. Запись событий: система прослушивает проблемы, сообщаемые пользователем, через библиотеку пользовательского интерфейса ACS. Он использует onUserReportedIssueEventHandler для сбора отзывов из пользовательского интерфейса приложения, включая ошибки и замечания пользователей.

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

3. Отзывы пользователей и уведомления. После отправки пользователи сразу же получают сведения о состоянии отчета с помощью уведомлений в приложении. Для успешной отправки уведомление содержит ссылку или упоминание на отправленный билет, позволяя пользователям отслеживать ход решения проблемы.

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

package com.azure.android.communication.ui.callingcompositedemoapp

import android.app.Application
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.content.Intent
import android.net.Uri
import android.os.Build
import androidx.core.app.NotificationCompat
import androidx.core.app.NotificationManagerCompat
import com.azure.android.communication.ui.calling.CallCompositeEventHandler
import com.azure.android.communication.ui.calling.models.CallCompositeCallHistoryRecord
import com.azure.android.communication.ui.calling.models.CallCompositeUserReportedIssueEvent
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.launch
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaTypeOrNull
import okhttp3.RequestBody.Companion.asRequestBody
import org.threeten.bp.format.DateTimeFormatter
import java.io.File
import java.io.IOException

/**
 * This class is responsible for handling user-reported issues within the Azure Communication Services Calling UI composite.
 * It implements the CallCompositeEventHandler interface to listen for CallCompositeUserReportedIssueEvents.
 * The class demonstrates how to send diagnostic information to a server endpoint for support purposes and
 * how to provide user feedback through notifications.
 */
class UserReportedIssueHandler : CallCompositeEventHandler<CallCompositeUserReportedIssueEvent> {
    // Flow to observe user reported issues.
    val userIssuesFlow = MutableStateFlow<CallCompositeUserReportedIssueEvent?>(null)

    // Reference to the application context, used to display notifications.
    lateinit var context: Application

    // Lazy initialization of the NotificationManagerCompat for managing notifications.
    private val notificationManager by lazy { NotificationManagerCompat.from(context) }

    /**
     * Handles the event when a user reports an issue.
     * - Creates a notification channel for Android O and above.
     * - Updates the userIssuesFlow with the new event data.
     * - Sends the event data including user message, app and SDK versions, call history, and log files to a server.
     */
    override fun handle(eventData: CallCompositeUserReportedIssueEvent?) {
        createNotificationChannel()
        userIssuesFlow.value = eventData
        eventData?.apply {
            sendToServer(
                userMessage,
                debugInfo.versions.azureCallingUILibrary,
                debugInfo.versions.azureCallingLibrary,
                debugInfo.callHistoryRecords,
                debugInfo.logFiles
            )
        }
    }

    /**
     * Prepares and sends a POST request to a server with the user-reported issue data.
     * Constructs a multipart request body containing the user message, app versions, call history, and log files.
     */
    private fun sendToServer(
        userMessage: String?,
        callingUIVersion: String?,
        callingSDKVersion: String?,
        callHistoryRecords: List<CallCompositeCallHistoryRecord>,
        logFiles: List<File>
    ) {
        if (SERVER_URL.isBlank()) { // Check if the server URL is configured.
            return
        }
        showProgressNotification()
        CoroutineScope(Dispatchers.IO).launch {
            val client = OkHttpClient()
            val requestBody = MultipartBody.Builder().setType(MultipartBody.FORM).apply {
                userMessage?.let { addFormDataPart("user_message", it) }
                callingUIVersion?.let { addFormDataPart("ui_version", it) }
                callingSDKVersion?.let { addFormDataPart("sdk_version", it) }
                addFormDataPart(
                    "call_history",
                    callHistoryRecords.map { "\n\n${it.callStartedOn.format(DateTimeFormatter.BASIC_ISO_DATE)}\n${it.callIds.joinToString("\n")}" }
                        .joinToString("\n"))
                logFiles.filter { it.length() > 0 }.forEach { file ->
                    val mediaType = "application/octet-stream".toMediaTypeOrNull()
                    addFormDataPart("log_files", file.name, file.asRequestBody(mediaType))
                }
            }.build()

            val request = Request.Builder()
                .url("$SERVER_URL/receiveEvent")
                .post(requestBody)
                .build()

            client.newCall(request).enqueue(object : Callback {
                override fun onFailure(call: Call, e: IOException) {
                    CoroutineScope(Dispatchers.Main).launch {
                        onTicketFailed(e.message ?: "Unknown error")
                    }
                }

                override fun onResponse(call: Call, response: Response) {
                    CoroutineScope(Dispatchers.Main).launch {
                        if (response.isSuccessful) {
                            onTicketCreated(response.body?.string() ?: "No URL provided")
                        } else {
                            onTicketFailed("Server error: ${response.message}")
                        }
                    }
                }
            })
        }
    }

    /**
     * Displays a notification indicating that the issue ticket has been created successfully.
     * The notification includes a URL to view the ticket status, provided by the server response.
     */
    private fun onTicketCreated(url: String) {
        showCompletionNotification(url)
    }

    /**
     * Displays a notification indicating that the submission of the issue ticket failed.
     * The notification includes the error reason.
     */
    private fun onTicketFailed(error: String) {
        showErrorNotification(error)
    }

    companion object {
        // The server URL to which the user-reported issues will be sent. Must be configured.
        private const val SERVER_URL = "${INSERT_YOUR_SERVER_ENDPOINT_HERE}"
    }

    /**
     * Creates a notification channel for Android O and above.
     * This is necessary to display notifications on these versions of Android.
     */
    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val name = "Report Submission"
            val descriptionText = "Notifications for report submission status"
            val importance = NotificationManager.IMPORTANCE_DEFAULT
            val channel = NotificationChannel("report_submission_channel", name, importance).apply {
                description = descriptionText
            }
            notificationManager.createNotificationChannel(channel)
        }
    }

    /**
     * Shows a notification indicating that the report submission is in progress.
     * This uses an indeterminate progress indicator to signify ongoing activity.
     */
    private fun showProgressNotification() {
        val notification = NotificationCompat.Builder(context, "report_submission_channel")
            .setContentTitle("Submitting Report")
            .setContentText("Your report is being submitted...")
            .setSmallIcon(R.drawable.image_monkey) // Replace with an appropriate icon for your app
            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
            .setProgress(0, 0, true) // Indeterminate progress
            .build()

        notificationManager.notify(1, notification)
    }

    /**
     * Shows a notification indicating that the report has been successfully submitted.
     * The notification includes an action to view the report status via a provided URL.
     */
    private fun showCompletionNotification(url: String) {
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
        val pendingIntent = PendingIntent.getActivity(
            context,
            0,
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
        )

        val notification = NotificationCompat.Builder(context, "report_submission_channel")
            .setContentTitle("Report Submitted")
            .setContentText("Tap to view")
            .setSmallIcon(R.drawable.image_monkey) // Replace with an appropriate icon for your app
            .setContentIntent(pendingIntent)
            .setAutoCancel(true) // Removes notification after tap
            .build()

        notificationManager.notify(1, notification)
    }

    /**
     * Shows a notification indicating an error in submitting the report.
     * The notification includes the reason for the submission failure.
     */
    private fun showErrorNotification(error: String) {
        val notification = NotificationCompat.Builder(context, "report_submission_channel")
            .setContentTitle("Submission Error")
            .setContentText("Error submitting report\nReason: $error")
            .setSmallIcon(R.drawable.image_monkey) // Replace with an appropriate icon for your app
            .setPriority(NotificationCompat.PRIORITY_DEFAULT)
            .build()

        notificationManager.notify(1, notification)
    }
}

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

            callComposite.addOnUserReportedEventHandler(userReportedIssueEventHandler)

Общие сведения о поддержке iOS

Чтобы интегрировать сбор отзывов пользователей в приложениях iOS с помощью библиотеки пользовательского интерфейса Служб коммуникации Azure (ACS), разработчикам необходимо выполнить структурированный подход. Этот процесс включает запись отзывов пользователей, включая журналы ошибок и сведения о пользователе. После завершения эти сведения передаются на сервер для обработки. В этом разделе описаны шаги, необходимые для выполнения этой задачи.

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

Реализация формы поддержки

1. Регистрация обработчика событий. Начните с регистрации обработчика событий, который прослушивает проблемы, сообщаемые пользователем. Этот обработчик имеет решающее значение для записи отзывов непосредственно из интерфейса приложения iOS с помощью возможностей библиотеки пользовательского интерфейса ACS.

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

Сбор и обработка запросов на поддержку

1. Генерация события при действии пользователя: когда пользователь сообщает о проблеме через форму поддержки, обработчик событий фиксирует это действие. Такие сведения, как описание проблемы, журналы ошибок и все идентификаторы вызовов, должны быть подготовлены для отправки на сервер.

2. Структурирование данных для отправки: упорядочение захваченных данных в структурированном формате, подходящем для передачи. Подготовьте данные таким образом, чтобы он соответствовал ожидаемому формату конечной точки сервера, которая получает и обрабатывает запрос на поддержку.

Отправка данных на сервер

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

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

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

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

2. Стратегия уведомлений. Реализуйте стратегию доставки уведомлений пользователям, особенно на устройствах под управлением версий iOS, поддерживающих определенные платформы уведомлений. Локальные уведомления можно использовать для информирования пользователей о состоянии отчета или предоставлении обновлений по мере устранения проблемы.

Пример кода iOS

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

Следующий пример предназначен для встраивания хука в ваш обработчик событий.

Installation

let onUserReportedIssueHandler: (CallCompositeUserReportedIssue) -> Void = { issue in
    // Add a hook to this method, and provide it the Server endpoint + a result callback
    sendSupportEventToServer(server: self.issueUrl, event: issue) { success, result in
        if success {
            // Success: Convey the result link back to the user
        } else {
            // Error: Let the user know something has happened
        }
    }
}

Сетевой хук

import Foundation
import UIKit
import Combine
import AzureCommunicationUICalling
import Alamofire

/// Sends a support event to a server with details from a `CallCompositeUserReportedIssue`.
/// - Parameters:
///   - server: The URL of the server where the event will be sent.
///   - event: The `CallCompositeUserReportedIssue` containing details about the issue reported by the user.
///   - callback: A closure that is called when the operation is complete.
///               It provides a `Bool` indicating success or failure, and a `String`
///               containing the server's response or an error message.
func sendSupportEventToServer(server: String,
                              event: CallCompositeUserReportedIssue,
                              callback: @escaping (Bool, String) -> Void) {
    // Construct the URL for the endpoint.
    let url = "\(server)/receiveEvent" // Ensure this is replaced with the actual server URL.

    // Extract debugging information from the event.
    let debugInfo = event.debugInfo

    // Prepare the data to be sent as key-value pairs.
    let parameters: [String: String] = [
        "user_message": event.userMessage, // User's message about the issue.
        "ui_version": debugInfo.versions.callingUIVersion, // Version of the calling UI.
        "call_history": debugInfo.callHistoryRecords
            .map { $0.callIds.joined(separator: ",") }
            .joined(separator: "\n") // Call history, formatted.
    ]

    // Define the headers for the HTTP request.
    let headers: HTTPHeaders = [
        .contentType("multipart/form-data")
    ]

    // Perform the multipart/form-data upload.
    AF.upload(multipartFormData: { multipartFormData in
        // Append each parameter as a part of the form data.
        for (key, value) in parameters {
            if let data = value.data(using: .utf8) {
                multipartFormData.append(data, withName: key)
            }
        }

        // Append log files.
        debugInfo.logFiles.forEach { fileURL in
            do {
                let fileData = try Data(contentsOf: fileURL)
                multipartFormData.append(fileData,
                                         withName: "log_files",
                                         fileName: fileURL.lastPathComponent,
                                         mimeType: "application/octet-stream")
            } catch {
                print("Error reading file data: \(error)")
            }
        }
    }, to: url, method: .post, headers: headers).response { response in
        // Handle the response from the server.
        switch response.result {
        case .success(let responseData):
            // Attempt to decode the response.
            if let data = responseData, let responseString = String(data: data, encoding: .utf8) {
                callback(true, responseString) // Success case.
            } else {
                callback(false, "Failed to decode response.") // Failed to decode.
            }
        case .failure(let error):
            // Handle any errors that occurred during the request.
            print("Error sending support event: \(error)")
            callback(false, "Error sending support event: \(error.localizedDescription)")
        }
    }
}

Этот код Swift демонстрирует процесс отправки пользовательских проблем из приложения iOS с помощью Служб коммуникации Azure. Она обрабатывает сбор отзывов пользователей, упаковку диагностических сведений и асинхронную отправку в конечную точку сервера. Кроме того, он предоставляет основу для реализации механизмов обратной связи, обеспечивая информирование пользователей о состоянии своих отчетов и повышение общей надежности приложений и удовлетворенности пользователей.