Настройка Assistant SDK Android

Обновлено 17 июня 2024

Настройка SDK перед обращением к ассистенту выполняется в Application файле вашего приложения и состоит из следующих этапов:

• замена версии артефактов;
• подключение репозиториев Maven;
• получение доступа к интерфейсам SDK.

Замена версии артефактов

В блоке dependencies файла app/build.gradle прописана версия артефактов 1.0.0.9999 — ее нужно заменить на ту, что предоставляется в архиве:

dependencies {
    // версию 1.0.0.9999 нужно будет заменить на ту, что предоставит команда Assistant SDK
    implementation("ru.sberbank.sdakit.android:assistant-sdk_client_ext:1.0.0.9999")
    implementation("ru.sberbank.sdakit.android:core-ext:1.0.0.9999")
    // если шрифт Sber Sans не нужен, то этот артефакт можно отключить
    implementation("ru.sberbank.sdakit.android:core-font:1.0.0.9999")
}

Подключение репозиториев Maven

Для сборки проекта нужны репозитории mavenCentral и google. В корневом файле build.gradle они заданы через внутренние прокси Сбера, которые недоступны во внешней сети. Перед тем, как собирать демо-приложение, необходимо либо заменить их прямыми ссылками на mavenCentral/google, либо на свои прокси-аналоги (если они есть). Подробнее о подключении репозиториев Maven читайте в разделе Подключение SDK.

Получение доступа к интерфейсам SDK

Чтобы настроить SDK ассистента, передайте ряд зависимостей, которые SDK ассистента будет использовать во время своей работы.

Для этого в функции onCreate(), которая вызывается при запуске Application, вызовите функцию ApiProvidersComponent.install() и передайте в нее компоненты с интерфейсами SDK.

class exampleApp : Application() {
    override fun onCreate() {
        super.onCreate()

        ApiProvidersComponent.install(
        )
    }
}

Компоненты с интерфейсами SDK

Ниже представлены компоненты SDK, которые необходимо передать в функцию ApiProvidersComponent.install().

Адресная книга

Компонент для использования собственной адресной книги приложения. Если в приложении есть своя адресная книга, то здесь можно передать ее в качестве источника данных. Иначе используется системная адресная книга (если пользователь предоставил приложению соответствующее разрешение) — контакты подтягиваются с устройства стандартным Android API.

Если ваше приложение не Сбербанк Онлайн, с большой вероятностью этот компонент переопределять не нужно.

contactsDependencies = object : ContactsDependencies {
    override val contactSource: ContactSource? = null
},

Запись событий аналитики

Во время своей работы SDK отправляет события аналитики, используя CoreAnalytics — механизм журналирования событий аналитики. Переопределите компонент, чтобы хост приложения видел в своей системе аналитики то, как ведет себя SDK.

Если аналитика не используется, укажите CoreAnalyticsDependencies.empty() в качестве значения coreAnalytics.

По умолчанию события не записываются.

coreAnalyticsDependencies = object : CoreAnalyticsDependencies {
    override val coreAnalytics: CoreAnalytics? = null
},

Конфигурирование функциональности ВА

Список флагов, которые включают различные функции виртуального ассистента. Список необходимо переопределить.

coreConfigDependencies = object : CoreConfigDependencies {
    override val featureFlagManager = FeatureFlagManager.fromList(
        object : DarkCardsFeatureFlag {
            override fun areDarkCardsEnabled() = true
        },
        object : KpssFeatureFlag {
            override fun isAnimatedKpssEnabled() = true;
            override fun isDownloadResourcesEnabled() = true
        },
        object : EarconsFeatureFlag {
            override fun areEarconsEnabled() = true
        },
        object : PersonalAsrFeatureFlag {
            override fun isPersonalAsrEnabled() = true
        },
        object : CheckHashFeatureFlag {
            override fun isEnabled() = true;
            override fun grayListEnabled() = false;
        },
        object : MessageDebugFeatureFlag {
            override val isEnabled = true
        },
        object : SmartAppsFeatureFlag {
            override val isEmbeddedAppsEnabled = true // для типа EMBEDDED_APP
            override val isEnabled: Boolean = true // для типа WEB_APP
            override val isChatAppEnabled = true // для типа CHAT_APP
        },
        object : FakeVPSFeatureFlag {
            override fun isEnabled(): Boolean = true
        },
        object : ThemesFeatureFlag {
            override fun themeToggleEnabled() = true
        }
        object : SpotterFeatureFlag {
            override val spotterMode = SpotterMode.ENABLED_FOREGROUND
        },
    )
},

Здесь:

• DarkCardsFeatureFlag — использовать ли новые (темные) цвета для карточек; использовать ли новый фон.
• KpssFeatureFlag — флаг для КПСС.
• EarconsFeatureFlag — проверяет, включены ли звуки о начале/конце слушания, звуки при ошибках.
• PersonalAsrFeatureFlag — проверяет, включена ли отправка имен из адресной книги в ASR вместе с каждой голосовой сессией.
• CheckHashFeatureFlag — проверяет хеш картинки перед показом.
• MessageDebugFeatureFlag – проверяет, включен ли дебаг-режим, в котором можно по лонг-тапу копировать message_id сообщений.
• SmartAppsFeatureFlag — включает смартапы разных типов.
• FakeVPSFeatureFlag — подменяет ответы сервера, чтобы проверить, как отображаются разные сообщения. Флаг используется только в тестовых приложениях и не включается в релизную версию.
• ThemesFeatureFlag – включает переключение тем.
• SpotterFeatureFlag — включает споттер.

Конфигурирование модуля работы с графикой

Политика валидации картинок.

Валидация картинок необходима, если есть соответствующее требование безопасности — это можно уточнить у отдела безопасности на стороне хоста приложения. Если валидировать нужно, ознакомьтесь с описанием внутри ImageUrlValidationPolicy.kt: там описаны все режимы валидации.

coreGraphicsDependencies = object : CoreGraphicsDependencies {
    override val imageUrlValidationPolicy =
        ImageUrlValidationPolicy.HashCheckValidationPolicy { emptyList() }
},

Обработчик контекста приложения

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

corePlatformDependencies = DefaultCorePlatformDependencies

Журналирование

Параметры журналирования событий виртуального ассистента.

Если специального журналирования в ассистенте не нужно, и журналов релизной сборки достаточно, можно использовать CoreLoggingDependencies.empty().

coreLoggingDependencies = object : CoreLoggingDependencies {
    /**
     * Для тестирования и отладки можно задать безусловное журналирование.
     * Если оставить null, журналы событий ассистента будут отсутствовать в релизной сборке.
     */
    override val logMode: LoggerFactory.LogMode? = null

    /**
     * Объект позволяет задать собственную систему журналирования приложения.
     * Если собственная система отсутствует, можно оставить null.
     */
    override val coreLogger: CoreLogger? = null
},

Параметры диалога

С помощью компонента можно задать параметры сценария взаимодействия виртуального ассистента с пользователем:

• включение антифрод-функций в банковских сценариях;
• конфигурацию диалога с ассистентом;
• адрес электронной почты для фичи «Сообщить о проблеме»;
• режим навигации со свернутой шторкой.

dialogConfigDependencies = object : DialogConfigDependencies {
    /**
    * Включение антифрод функций в банковских сценариях.
    * Если приложение не поддерживает банковские сценарии, в качестве значения переменной можно указать AntiFraud.empty(). 
    */
    override val antiFraud = AntiFraud.empty()
    /**
    * Конфигурация диалога с ассистентом.
    */
    override val dialogConfiguration = DialogConfiguration()
    /**
    * Задайте здесь адрес, если нужно поменять дефолтный адрес почты для фичи "Сообщить о проблеме".
    * Если не менять, то будет использоваться дефолтный адрес "AssistantFeedback@sberbank.ru"
    */
    override val email: FeedbackEmailSource = FeedbackEmailSource.defaultEmail()
    /**
    * Задает режим новой навигации со свернутой шторкой. По умолчанию новая навигация выключена.
    * В этом примере включаем навигацию 2.0
    */
    override val hostNavigation2Availability = object : HostNavigation2Availability {
        override val isHostNavigation2Enabled: Boolean = true
},

Обработка внутренних ссылок

Компонент для настройки внутренних ссылок. Позволяет задать следующие параметры:

• Схему внутренних ссылок. Например, myapp://.
• Обработчик внутренних ссылок.
• Обработчик внешних ссылок http/https.
• Запасной (fallback) обработчик.

Также вы можете использовать настройки по умолчанию DialogDeepLinksDependencies.defaultConfig — этой стандартной реализации достаточно для базовой интеграции.

dialogDeepLinksDependencies = object : DialogDeepLinksDependencies {
    override val dialogDeepLinksConfig = DialogDeepLinksConfig(useFallbackHandler = true)
},

Подключение анимаций ассистента

Если в вашем CDN есть дополнительные анимации, здесь можно задать адрес этого CDN. Размещение анимаций в CDN позволяет уменьшить размер приложения.

downloadsDependencies = object : DownloadsDependencies {
    /**
    * Если нужно загружать дополнительные анимации для ассистента, то здесь нужно задать адрес до своего CDN.
    */
    override val mapperConfig = MapperConfig(host = "https://your.cdn.goes.here/")
},

Подключение шрифтов

Компонент, который передает шрифты хосты в SDK. Опциональный компонент, скорее всего не нужен.

messagesDependencies = object : MessagesDependencies {
    /**
    * Предоставление хостом своих шрифтов в сдк. Скорее всего вам это не нужно.
     */
    override val hostFontProvider: HostFontProvider?
                    get() = null
},

Передача содержимого в host_meta

При необходимости вместо null возвращать корректно составленный объект. Метод getHostMeta будет вызывать перед каждым запросом в NLP-платформу.

platformLayerDependencies = object : PlatformLayerDependencies {
    override val hostMetaProvider: HostMetaProvider = object : HostMetaProvider {
        override fun getHostMeta(): HostMetaModel? {
            return null
        }
    }
}, 

Провайдер оплаты по SberPay

Компонент для настройки оплаты по SberPay. Эта функциональность пока недоступна для приложений, которые не относятся к банковским.

sbolPaylibNativeDependencies = DefaultSbolPaylibNativeDependencies(),

Политика прогрева сессии авторизации

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

sessionDependencies = SessionDependencies.empty(),

Поиск по фичам

Компонент позволяет задать источник для поиска по фичам.

smartSearchDependencies = object : SmartSearchDependencies {
    override val smartSearchSource: SmartSearchSource? = null
},

Конфигурация загрузчика ресурсов

Здесь можно задать настройки для загрузчика ресурсов КПСС.

kpssDependencies = object : KpssDependencies {
    /**
    * Если нужен особый подход к КПСС - можно переопределить эту фабрику. Подробнее см. МП СберДРУГ
    */
    override val kpssAnimationProviderFactory: KpssAnimationProviderFactory? = null
    /**
    * Задает пути на CDN и в локальном кеше для ресурсов КПСС.
    */
    override val kpssDownloaderConfig = KpssDownloaderConfig(remotePath = "/VA", localPath = "/VA")
},

Настройка платежей

Здесь можно настроить платежный бэкенд и провайдера оплаты по SberPay.

Платежи в SDK еще не готовы к использованию в приложениях.

paylibConfigDependencies = object : PaylibConfigDependencies {
    /**
    * Конфигурация платежного бэкенда. Пока платежи в SDK еще не готовы к использованию в приложениях.
    */
    override val backendUrlProvider = object : BackendUrlProvider {
        override val backendUrl = ""
    }
},
/**
* Провайдер оплаты по SberPay.
* В обычных не-банковских приложениях эта функциональность пока еще недоступна.
*/
paylibNativeDependencies = DefaultPaylibNativeDependencies(),
},

Обработчик сертификатов для смартапов

Eсли в приложении используются сертификаты, и смартапы типа Canvas App, разработанные для поверхности на основе WebView, требуют сертификаты, то через этот компонент можно передать эти сертификаты в Canvas App (веб-аппы).

smartAppsApiDependencies = object : SmartAppsApiDependencies {
    /**
    * Хэндлер для сертификатов в SmartApps, которые защищены аутентификацией
    */
    override val webViewClientCertRequestHandler: WebViewClientCertRequestHandler? = null
},

Конфигурирование смартапов

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

Пока смартапы в SDK не готовы к использованию в приложениях.

smartAppsDependencies = SmartAppsDependencies.mobileConfig(),

Умный поиск

Здесь можно задать параметры умного поиска.

Используется только в Сбербанк Онлайн.

smartSearchDependencies = object : SmartSearchDependencies {
    /**
    * Позволяет задать источник для поиска по фичам
    */
    override val smartSearchSource: SmartSearchSource? = null
},

Авторизация приложения в службе обработки речи

В этом блоке параметров необходимо указать идентификационные данные, которые вы получаете вместе с AAR-библиотекой:

• surface — название поверхности. Для мобильных приложений — COMPANION.
• channel — название канала. Предоставляется при получении библиотеки SDK.
• vpsTokenProvider — токен авторизации, полученный при запросе библиотеки SDK.

vpsConfigDependencies = object : VpsConfigDependencies {
    /**
    * Конфигурация подключения к серверу VPS.
    */
    override val vpsClientConfig = VPSClientConfig(
        clientInfo = ClientInfoFactory.create(
            /**
            * Это константа, которую нужно получить один раз.
            * Скорее всего, будет как-то соотноситься с именем приложения.
            */
            surface = "YOUR_APP_SURFACE",
            /**
            * Здесь скорее всего будет версия приложения.
            */
            surfaceVersion = "YOUR_APP_VERSION",
            /**
            * Имя пакета приложения. Можно оставить так.
            */
            packageName = packageName
            ),
        /**
        * если не планируется подключаться к тестовым стендам, то это поле можно не менять
        **/
        serverUrl = resources.getString(R.string.preference_assistant_vps_endpoint_uri_prod_2),
        /**
        * это константа, которую нужно получить один раз
        */
        channel = "YOUR_APP_CHANNEL"
        )
    /**
    * Указывает режим работы с токенами авторизации
    **/
    override val vpsTokenMode = VpsTokenMode.SingleTokenProvider(
        /**
        * Предоставляет токен авторизации в SDK.
        */
        object : VPSTokenProvider {
            override fun requestToken(cause: VPSTokenProvider.RequestCause): Single<TokenValue> =
Single.just(TokenValue.esa("TEST_TOKEN"))
        }
    )
},

Подключение ресурсов споттера

Здесь можно задать пути до CDN и локального кеша для ресурсов споттера.

Споттер — технология голосовой активации, которая позволяет виртуальному ассистенту реагировать на свое имя и отвечать на запрос клиента.

Мы рекомендуем интегрировать споттер: он дает возможность активировать ассистента не нажатием на кнопку, а голосом с помощью активационного слова («Салют», «Сбер», «Афина», «Джой»).

spotterConfigRemoteDependencies = object : SpotterConfigRemoteDependencies 
    /**
    * Задает пути на CDN и в локальном кеше для ресурсов споттера.
    */
    override val spotterModelDownloaderConfig =
        SpotterModelDownloaderConfig(remotePath = "VA/spotter", localPath = "VA/spotter")
},

Конфигурация хранилища

В SDK история взаимодействия с ассистентом хранится в локальной базе данных. Если в приложении используется мультиаккаунт, то можно хранить историю для каждого пользователя отдельно — для этого приложение решает, каким будет ID для каждого пользователя из мультиаккаунта. В этом компоненте можно задать ID пользователя, чтобы разделять историю. Если этот функционал не нужен, используйте StorageDependencies.defaultConfig().

storageDependencies = object : StorageDependencies {
    /**
    * Задает id пользователя, для того чтобы разделять историю по пользователям (используется в Сбол)
    */
    override val userStorageConfig: UserStorageConfig = UserStorageConfig()
},

Настройки WebView

Масштабировать вебвью в мобильных приложениях не нужно. Используйте WebViewScalingDependencies.defaultConfig().

webViewScalingDependencies = WebViewScalingDependencies.defaultConfig()