VKarmaneSDK - это библиотека, в которой содержатся инструменты упрощающие интеграцию функциии "Заполнить из ВКармане".
Требования
Для работы VKarmaneSDK необходим iOS версии 9.0 и выше.
Как подключить к проекту?
VKarmaneSDK распостраняется через CocoaPods. Для подключения добавьте следующую строчку в Podfile:
pod'VKarmaneSDK'
Для запуска тествого приложения, необходимо выполнить pod install из папки Example.
В папке Assets находятся изображения, которые можно использовать в ваших приложениях на элементах для запуска процессов взаимодействия с ВКармане.
Подготовка к работе
Для того что бы использовать функцию "Заполнить из ВКармане" в production необходимо, что бы url схема вашего приложения, была добавлена в список доверенных, который содержится в нашем приложении. По вопросам добавления, можно связаться с нами написав на vkarmane-sdk@tinkoff.ru.
Примеры использования SDK
Проверка установки ВКармане
if VKarmaneSDK.isAppInstalled {showVkarmaneButton()}else{hideVkarmameButton()}
Схема запроса и получения данных документов
В Вашем приложении генерируется пара ключей (предпочтительно выполнять эту операцию асинхронно, т.к. она достаточно тяжелая и может кратковременно блокировать интерфейс).
Публичный ключ кодируется в Base64.
Вызывается метод создания ссылки для перехода во ВКармане с интересующими параметрами.
Выполняется переход по ссылке.
Обрабатывается полученный от ВКармане URL, в котором расшифровываются данные изначально сгенерированным ключом.
Пример получения паспортных данных пользователя:
// 1-2. Создаем и сохраняем ключи, кодируем публичный ключletkeys=try!VKarmaneSDK.makeKeys()self.keys = keys
letpublicKeyBase64=try! keys.publicKey.getData().base64EncodedString()// 3. Создаем ссылку// Метод может выбросить ошибку `VKarmaneSDK.GetDocumentsLinkBuilderError`, если параметры не прошли валидациюletvkarmaneLink=try!VKarmaneSDK.GetDocumentsLinkBuilder(xSource:"Vkarmane example",
xSuccessLink:"vkarmanesdkexample://documents_success",
xErrorLink:"vkarmanesdkexample://documents_error",
xCancelLink:"vkarmanesdkexample://documents_cancel",
kinds:[DocumentKind.RusNationalID],
publicKey: publicKeyBase64,
isMultichoice: false).build()// 4. ПереходимUIApplication.shared.open(vkarmaneLink, options:[:])// 5. В AppDelegate получаем и расшифровываем данные изначально сгенерированным `keys.privateKey`func application(_ application:UIApplication, open url:URL, options:[UIApplication.OpenURLOptionsKey:Any])->Bool{
if let vkarmaneResult =getResult(from: url){// handle data or error}}func getResult(from url:URL)->Result?{
guard let components =URLComponents(url: url, resolvingAgainstBaseURL: false)else{returnnil}
switch components.host {caseConst.successPath:do{return.success(jsonString:tryVKarmaneSDK.getJsonFromLink(url, privateKey:self.keys.privateKey))}catch{return.failure(error: error)}caseConst.errorPath:return.failure(error:VKarmaneSDK.getErrorFromLink(url))caseConst.cancelPath:return.cancelled
default:returnnil}}
Вызвав getJsonFromLink(url) можно получить как JSON-строку, так и ошибку из пришедшего результата. Если для xSuccessLink и xErrorLink указаны разные ссылки, для получения ошибки можно испольовать отдельный метод getErrorFromLink(url) (как в примере выше).
Описание протокола
Протокол взаимодействия реализованный в SDK, основан на x-callback-url. В общем виде deeplink для запуска ВКармане выглядит следующем образом:
Предложить пользователю выбрать один (или несколько) документов с типами указанными в action-params
Доступные параметры действий (action-params)
action
Название
Описание
Тип
Обязательность
Значение по-умолчанию
get_documents
kinds
Список типов документов
VKarmaneSDK.DocumentKind
Да
-
get_documents
publicKey
Публичный ключ RSA-2048, закодированный в Base64
String
Да
-
get_documents
isMultichoice
Переключение режимов выбора документа, если передан true то пользователь может выбрать несколько документов
Boolean
Нет
false
Параметры для запуска ВКармане x-callback-params
Название
Описание
x-source
Название стороннего приложения
x-success
Deeplink для вызова стороннего приложения с данными выбранных пользователем документов, в качестве параметра data, в этот deeplink будет переден url encoded JSON c содержимым документа, без фото
x-error
Deeplink для вызова стороннего приложения в случае возникновения ошибки. В качестве параметра code в ссылку добавится параметр code содержащий информацию об ошибке, см. ниже возможные коды ошибок.
x-cancel
Deeplink для вызова стороннего приложения, в случае отмены пользователем опрерации
Все перечисленные параметры обязательны
Коды ошибок (code)
Значение
Описание
1
Полученный deeplink приложением ВКармане не поддерживается
2
Некорректный action
3
Некорректные x-callback-params
4
Некорректные action-params
5
Во время обработки deeplink в приложении ВКармане произошла ошибка
6
Пользователь не авторизован во ВКармане
7
Ошибка криптографии
Для обеспечения безопасности пользователя при возникновении ошибки с кодом 3 процесс прерывается в приложении ВКармане, с сообщением, показывающим, что были переданы неверные параметры.
Поддерживаемые типы документов (kinds)
Значение
Описание
RusNationalID
Паспорт РФ
RusDriversLic
ВУ
RusDriversLicOld
ВУ старого образца
RusDriversLicOldest
ВУ самого старого образца
RusInternationalID
Загранпаспорт
RusSNILS
СНИЛС
RusINN
ИНН
RusBirthCert
Свидетельство о рождении
RusMedIns
Полис ОМС
RusVehicleRegID
СТС
RusPTS
ПТС
RusOSAGO
ОСАГО
RusKASKO
КАСКО
RusMilitaryCard
Военный билет
BankCard
Банковская карта
Sample
Содержит пример интеграции "Заполнить из ВКармане".