# Коллбеки и обработчики Android SDK

# Уведомление об изменении статуса SDK

Чтобы получать уведомления об изменениях статуса SDK, используйте .withHandlers(onStateChanged=onSDKStateChangedHandler) или .withStateChangedHandler(stateChangedHandler) в CBRMobileSDK.Builder.

Обработчик принимает два параметра:

newStatus — текущий статус SDK.
prevStatus — предыдущий статус.

Пример, который перечисляет все возможные статусы:

      Kotlin
    
      Java
    
Copy
val onSDKStateChangedHandler: (CBRSDKState, CBRSDKState) -> Unit = { newStatus, prevStatus ->
			Timber.d("onSDKStateChangedHandler: $prevStatus -> $newStatus")
			when (newStatus) {
					is CBRSDKState.Ready -> Timber.d("SDK is ready")
					is CBRSDKState.Failed -> {
							when (newStatus) {
									is CBRSDKState.Failed.ApplicantNotFound -> Timber.e(newStatus.message)
									is CBRSDKState.Failed.ApplicantMisconfigured -> Timber.e(newStatus.message)
									is CBRSDKState.Failed.InitialLoadingFailed -> Timber.e(newStatus.exception,"Initial loading error")
									is CBRSDKState.Failed.InvalidParameters -> Timber.e(newStatus.message)
									is CBRSDKState.Failed.NetworkError -> Timber.e(newStatus.exception,newStatus.message)
									is CBRSDKState.Failed.Unauthorized -> Timber.e(newStatus.exception,"Invalid token or a token can't be refreshed by the SDK. Please, check your token expiration handler")
									is CBRSDKState.Failed.Unknown -> Timber.e(newStatus.exception, "Unknown error")
							}
					}
					is CBRSDKState.Initial -> Timber.d("No verification steps are passed yet")
					is CBRSDKState.Incomplete -> Timber.d("Some but not all verification steps are passed over")
					is CBRSDKState.Pending -> Timber.d("Verification is in pending state")
					is CBRSDKState.FinallyRejected -> Timber.d("Applicant has been finally rejected")
					is CBRSDKState.TemporarilyDeclined -> Timber.d("Applicant has been declined temporarily")
					is CBRSDKState.Approved -> Timber.d("Applicant has been approved")
			}
}
val cbrSdk = CBRMobileSDK.Builder(this).withHandlers(onStateChanged = onSDKStateChangedHandler)
CBRStateChangedHandler stateChangedHandler = (prevStatus, newStatus) -> {
			Timber.d("The SDK state was changed: " + prevStatus + " -> " + newStatus);
			if (newStatus instanceof CBRSDKState.Ready) {
					Timber.d("SDK is ready");
			} else if (newStatus instanceof CBRSDKState.Failed.Unauthorized) {
					Timber.e(((CBRSDKState.Failed.Unauthorized) newStatus).getException(), "Invalid token or a token can't be refreshed by the SDK. Please, check your token expiration handler");
			} else if (newStatus instanceof CBRSDKState.Failed.Unknown) {
					Timber.e(((CBRSDKState.Failed.Unknown) newStatus).getException(), "Unknown error");
			} else if (newStatus instanceof CBRSDKState.Initial) {
					Timber.d("No verification steps are passed yet");
			} else if (newStatus instanceof CBRSDKState.Incomplete) {
					Timber.d("Some but not all verification steps are passed over");
			} else if (newStatus instanceof CBRSDKState.Pending) {
					Timber.d("Verification is in pending state");
			} else if (newStatus instanceof CBRSDKState.FinallyRejected) {
					Timber.d("Applicant has been finally rejected");
			} else if (newStatus instanceof CBRSDKState.TemporarilyDeclined) {
					Timber.d("Applicant has been declined temporarily");
			} else if (newStatus instanceof CBRSDKState.Approved) {
					Timber.d("Applicant has been approved");
			}
};
CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withStateChangedHandler(stateChangedHandler).build();

Статусы SDK

Статус	Описание
`Ready`	SDK инициализирован и готов к запуску.
`Failed`	SDK завершился с ошибкой.
`Initial`	Шаги проверки еще не пройдены.
`Incomplete`	Пройдена часть шагов проверки.
`Pending`	Ожидается проверка пользователя.
`TemporarilyDeclined`	Временный отказ.
`FinallyRejected`	Окончательный отказ.
`Approved`	Анкета пользователя одобрена.

Типы ошибок

Ошибка	Описание
`ApplicantNotFound`	Анкета пользователя не найдена.
`ApplicantMisconfigured`	Анкета пользователя найдена, но настройки некорректные (например, отсутствует `idDocs`).
`InitialLoadingFailed`	Ошибка начальной загрузки с сервера.
`InvalidParameters`	Некорректные параметры.
`NetworkError`	Ошибка сети (пользователь видит экран «Network Oops»).
`Unknown`	Неизвестная ошибка.
`InitializationError`	Ошибка инициализации.

# Уведомление о событиях

Обработчик событий получать уведомления о событиях, происходящих в процессе обработки.
События передаются в обработчик в виде экземпляров класса, унаследованных от базового класса CBREvent. Таким образом, каждое событие содержит eventType и набор параметров, упакованных в словарь payload.

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

      Kotlin
    
      Java
    
Copy
val onEventHandler: CBREventHandler = object : CBREventHandler {
			override fun onEvent(event: CBREvent) {
					when (event) {
							is CBREvent.CBREventStepInitiated -> {
									Timber.d("onEvent: step initiated")
							}
							is CBREvent.CBREventStepCompleted -> {
									Timber.d("onEvent: step completed")
							}
					}
			}
}
val cbrSdk = CBRMobileSDK.Builder(this).withEventHandler(onEventHandler)
CBREventHandler eventHandler = cbrEvent -> {
			if (cbrEvent instanceof CBREvent.CBREventStepInitiated) {
					Timber.d("onEvent: step initiated");
			} else if (cbrEvent instanceof CBREvent.CBREventStepCompleted) {
					Timber.d("onEvent: step completed");
			}
};
CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withEventHandler(eventHandler).build();

# Уведомление о завершении работы SDK

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

result:
- CBRCompletionResult.SuccessTermination — успешное завершение работы SDK, включая вызов dismiss().
- CBRCompletionResult.AbnormalTermination — ошибка, произошедшая при работе SDK. Дополнительную информацию можно получить из объекта exception.
state: состояние SDK при его закрытии. Возможные состояния см. в разделе Уведомление об изменении состояния SDK.

      Kotlin
    
      Java
    
Copy
val onSDKCompletedHandler: (CBRCompletionResult, CBRSDKState) -> Unit = { (result, state) ->
			when (result) {
					is CBRCompletionResult.SuccessTermination -> Timber.d("The SDK finished successfully")
					is CBRCompletionResult.AbnormalTermination -> Timber.e(result.exception, "The SDK got closed because of errors")
			}
}
val cbrSdk = CBRMobileSDK.Builder(this).withHandlers(onCompleted = onSDKCompletedHandler)
CBRCompleteHandler completeHandler = (result, state) -> {
			Timber.d("The SDK is finished. Result: " + result + " , State: " + state);
			Toast.makeText(applicationContext, "The SDK is finished. Result: $result, State: $state", Toast.LENGTH_SHORT).show();
			if (result instanceof CBRCompletionResult.SuccessTermination) {
					Timber.d(result.toString());
			} else if (result instanceof CBRCompletionResult.AbnormalTermination) {
					Timber.d(((CBRCompletionResult.AbnormalTermination) result).getException());
			}
};
CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withCompleteHandler(completeHandler).build();

# Истечение срока действия токена

Так как срок действия токена доступа (accessToken) ограничен, важно уметь его обновлять. Для этого нужно передать tokenHandler в CBRMobileSDK.Builder.

Обработчик делает запрос на ваш сервер, получает новый токен и затем передает его обратно в SDK.

      Kotlin
    
      Java
    
Copy
val tokenHandler = object : TokenExpirationHandler {
	override fun onTokenExpired(): String? {
		val newToken = "..." // получите новый токен с бэкенда
		return newToken
	}
}
TokenExpirationHandler tokenUpdater = () -> {
		String newAccessToken = "..."; // получите новый токен с бэкенда
		return newAccessToken;
	};

Внимание:

onTokenExpired не должен вызываться в потоке пользовательского интерфейса.

# Уведомление об ошибках SDK

Чтобы получать уведомления об ошибках, используйте .withHandlers(onError=onSDKErrorHandler) или .withErrorHandler(errorHandler) в CBRMobileSDK.Builder.

      Kotlin
    
      Java
    
Copy
val onSDKErrorHandler: (CBRException) -> Unit = { exception ->
	Timber.d("The SDK throws an exception. Exception: $exception")
	when (exception) {
		is CBRException.Api -> Timber.d("Api exception. ${exception.description}")
		is CBRException.Network -> Timber.d(exception, "Network exception.")
		is CBRException.Unknown -> Timber.d(exception, "Unknown exception.")
	}
}
val cbrSdk = CBRMobileSDK.Builder(this).withHandlers(onError = onSDKErrorHandler)
CBRErrorHandler errorHandler = e -> {
	Timber.d("The SDK throws an exception. Exception: %s", e);
	if (e instanceof CBRException.Api) {
			Timber.d("Api exception. %s", ((CBRException.Api) e).getDescription());
	} else if (e instanceof CBRException.Network) {
			Timber.d(e, "Network exception.");
	} else if (e instanceof CBRException.Unknown) {
			Timber.d(e, "Unknown exception.");
	}
};
CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withErrorHandler(errorHandler).build();

# Уведомление о результате действий (actions)

Этот обработчик может использоваться для получения результата действия пользователя (action) и управления сценарием проверки живости (liveness).

Обработчик принимает два параметра:

actionId : String —идентификатор действия пользователя (action).
answer : String — ответ модуля проверки живости (liveness).
Возможные значения: GREEN/YELLOW/RED/ERROR/null.

Обработчик должен вернуть CBRActionResult:

CBRActionResult.Continue — продолжить сценарий действия по умолчанию (показать экран результата и т. д.).
CBRActionResult.Cancel — отменить сценарий действия по умолчанию (закрыть SDK без экрана результата).

      Kotlin
    
      Java
    
Copy
val onActionResultHandler: CBRActionResultHandler = object : CBRActionResultHandler {
	override fun onActionResult(actionId: String, actionType: String, answer: String?, allowContinuing: Boolean): CBRActionResult {
			Timber.d("Face Auth action result: actionId: $actionId answer: $answer")
			// используем сценарий по умолчанию
			return CBRActionResult.Continue
	}
}
val cbrSdk = CBRMobileSDK.Builder(this).withActionResultHandler(onActionResult)
CBRActionResultHandler actionResultHandler = (actionId, actionType, answer, allowContinuing) -> {
	Timber.d("Action Result: actionId: " + actionId + ", answer: " + answer);
	return CBRActionResult.Continue;
};
CBRMobileSDK.SDK cbrSdk = new CBRMobileSDK.Builder(requireActivity()).withActionResultHandler(actionResultHandler).build();

# Обработчик иконок

С помощью этого обработчика, можно настраивать иконки на экранах IDnGO SDK. В данный момент поддерживаются только иконки инструкций и иконки документов (для экрана выбора документа).

Обработчик предоставляет ключ иконки и тематический контекст, возвращая drawable или null, если drawable не требуется.

SDK использует следующие ключи:

default/do_idCard — иконка для инструкции к удостоверению личности (экран инструкций, блок DO).
default/dont_idCard — иконка для инструкции к удостоверению личности (экран инструкций, блок DON'T).
default/do_idCard_backSide — иконка для инструкции к оборотной стороне удостоверения личности (экран инструкций, блок DO).
default/dont_idCard_backSide — иконка для инструкции к оборотной стороне удостоверения личности (экран инструкций, блок DON'T).
default/do_passport — иконка для инструкции к паспорту (экран инструкций, блок DO).
default/dont_passport — иконка для инструкции по паспорту (экран инструкций, блок DON'T).
default/facescan — иконка для инструкции к проверке живости (liveness).
IdentityType/<DOCUMENT TYPE> — иконка для элемента документа на экране выбора документа, где <DOCUMENT TYPE> — это PASSPORT, DRIVERS, RESIDENCE_PERMIT или другой документ.
Flag/<COUNTRY_CODE> — иконка для флага страны, где <COUNTRY_CODE> — это код страны Альфа-2 (ISO 3166-1).

Вы можете предоставить свои собственные иконки или переопределить существующие, расширив CBRDefaultIconHandler.

      Kotlin
    
Copy
val iconHandler = object : CBRIconHandler {
	override fun onResolveIcon(context: Context, key: String): Drawable? {
		val iconRes = when {
			key == "default/do_idCard" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_do
			key == "default/do_passport" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_do_passport
			key == "default/dont_idCard" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_dont
			key == "default/dont_passport" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_dont_passport
			key == "default/facescan" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_liveness
			key == "default/do_idCard_backSide" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_do_back
			key == "default/dont_idCard_backSide" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_intro_dont_back
			key == "IdentityType/PASSPORT" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_iddoc_passport
			key == "IdentityType/DRIVERS" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_iddoc_driving_license
			key == "IdentityType/RESIDENCE_PERMIT" -> ru.cyberity.cbr.core.R.drawable.cbr_ic_iddoc_residence_permit
			key.startsWith("IdentityType/") -> ru.cyberity.cbr.core.R.drawable.cbr_ic_iddoc_id_card
			else -> -1
		}
		return iconRes.takeIf { it != -1 }?.let { ResourcesCompat.getDrawable(context.resources, it, context.theme) }
	}
}
val cbrSdk = CBRMobileSDK.Builder(this).withIconHandler(iconHandler)