ym88659208ym87991671
Настройка SDK | Документация для разработчиков

Настройка 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()
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.