Android-SDK-Integrationsleitfaden
Übersicht
Das MTVerify Android SDK ist ein SDK zur Rufnummernauthentifizierung, das eine schnelle, sichere Rufnummernverifizierung auf Carrier-Niveau bietet.
Hauptfunktionen
- SDK-Initialisierung: Automatisches Abrufen der Konfiguration und Initialisierung über den AppKey
- Abdeckungsprüfung: Prüfen, ob die aktuelle Netzwerkumgebung den Authentifizierungsdienst unterstützt
- Rufnummernauthentifizierung: Rufnummernauthentifizierung einleiten und ein Authentifizierungs-Token erhalten
Systemanforderungen
- Android 5.0 (API 21) und höher
- Das Gerät des Nutzers hat mobile Daten aktiviert
Integrationsleitfaden
Berechtigungskonfiguration
Das aar-Paket fordert die folgenden Berechtigungen an:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
Diesen Codeblock im schwebenden Fenster anzeigen
Carrier-Konfiguration
Da die Carrier-Schnittstelle eine HTTP-Klartextübertragung erfordert, müssen Sie die Netzwerksicherheitsrichtlinie in der AndroidManifest.xml Ihrer Anwendung konfigurieren:
<application
android:networkSecurityConfig="@xml/mtverify_network_security_config"
...>
...
</application>
<application
android:networkSecurityConfig="@xml/mtverify_network_security_config"
...>
...
</application>
Diesen Codeblock im schwebenden Fenster anzeigen
Außerdem müssen Sie die Datei mtverify_network_security_config.xml in das Verzeichnis res/xml/ Ihrer Anwendung kopieren. Diese Datei finden Sie im heruntergeladenen Installationspaket.
Methodenliste
- setLogEnable - Den Log-Schalter setzen
- init - Das SDK initialisieren
- checkCoverage - Die Abdeckung prüfen
- startAuthentication - Authentifizierung durchführen
init
Initialisiert das MTVerify SDK und legt App-Schlüssel und Umgebungskonfiguration fest.
Methodensignatur
@JvmStatic
fun init(
context: Context,
appkey: String,
environment: IPEnvironment = IPEnvironment.PRODUCTION,
callback: InitCallback? = null
)
@JvmStatic
fun init(
context: Context,
appkey: String,
environment: IPEnvironment = IPEnvironment.PRODUCTION,
callback: InitCallback? = null
)
Diesen Codeblock im schwebenden Fenster anzeigen
Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| context | Context | Ja | Android-Kontextobjekt |
| appkey | String | Ja | App-Schlüssel zur Identifizierung der App |
| environment | IPEnvironment | Nein | Umgebungstyp, Standard ist SANDBOX. Optionen: - IPEnvironment.SANDBOX: Test-/Sandbox-Umgebung - IPEnvironment.PRODUCTION: Produktionsumgebung |
| callback | InitCallback? | Nein | Initialisierungs-Callback-Schnittstelle zum Empfangen des Initialisierungsergebnisses |
Rückgabewert
Keiner
Callback-Ergebnis
Das Initialisierungsergebnis wird über InitCallback.onComplete(result: InitResult) zurückgegeben:
data class InitResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, andere Zahlen bedeuten Fehler
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
data class InitResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, andere Zahlen bedeuten Fehler
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
Diesen Codeblock im schwebenden Fenster anzeigen
Anwendungsbeispiel
MTVerifyApi.init(
context = this,
appkey = "your_app_key",
environment = IPEnvironment.PRODUCTION,
callback = object : InitCallback {
override fun onComplete(result: InitResult) {
if (result.code == 0) {
// Initialisierung erfolgreich
Log.d("MTVerify", "Initialisierung erfolgreich: ${result.message}")
} else {
// Initialisierung fehlgeschlagen
Log.e("MTVerify", "Initialisierung fehlgeschlagen: ${result.message}")
}
}
}
)
MTVerifyApi.init(
context = this,
appkey = "your_app_key",
environment = IPEnvironment.PRODUCTION,
callback = object : InitCallback {
override fun onComplete(result: InitResult) {
if (result.code == 0) {
// Initialisierung erfolgreich
Log.d("MTVerify", "Initialisierung erfolgreich: ${result.message}")
} else {
// Initialisierung fehlgeschlagen
Log.e("MTVerify", "Initialisierung fehlgeschlagen: ${result.message}")
}
}
}
)
Diesen Codeblock im schwebenden Fenster anzeigen
Hinweise
- Sie müssen zuerst die Methode
init()aufrufen, um das SDK zu initialisieren, bevor Sie andere Funktionen verwenden können - Der Initialisierungsprozess ruft
clientIdundredirectUrlüber eine HTTP-Anfrage ab und erfordert eine Netzwerkverbindung
setLogEnable
Setzt den Log-Schalter, um die Log-Ausgabe des SDK zu steuern.
Methodensignatur
@JvmStatic
fun setLogEnable(enable: Boolean)
@JvmStatic
fun setLogEnable(enable: Boolean)
Diesen Codeblock im schwebenden Fenster anzeigen
Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| enable | Boolean | Ja | true aktiviert das Logging, false deaktiviert jegliche Log-Ausgabe |
Anwendungsbeispiel
// Logging aktivieren
MTVerifyApi.setLogEnable(true)
// Logging deaktivieren
MTVerifyApi.setLogEnable(false)
// Logging aktivieren
MTVerifyApi.setLogEnable(true)
// Logging deaktivieren
MTVerifyApi.setLogEnable(false)
Diesen Codeblock im schwebenden Fenster anzeigen
checkCoverage
Prüft, ob die angegebene Rufnummer den IPification-Verifizierungsdienst unterstützt.
Methodensignatur
@JvmStatic
fun checkCoverage(
context: Context,
phoneNumber: String,
callback: CoverageCallback? = null
)
@JvmStatic
fun checkCoverage(
context: Context,
phoneNumber: String,
callback: CoverageCallback? = null
)
Diesen Codeblock im schwebenden Fenster anzeigen
Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| context | Context | Ja | Android-Kontextobjekt |
| phoneNumber | String | Ja | Ländervorwahl + Rufnummer des Nutzers |
| callback | CoverageCallback? | Nein | Callback-Schnittstelle der Abdeckungsprüfung |
Rückgabewert
Keiner
Callback-Ergebnis
Das Prüfergebnis wird über CoverageCallback.onComplete(result: CoverageResult) zurückgegeben:
data class CoverageResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, andere Zahlen bedeuten Fehler
val isAvailable: Boolean, // Ob verfügbar (unterstützter Carrier)
val operatorCode: String?, // Carrier-Code
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
data class CoverageResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, andere Zahlen bedeuten Fehler
val isAvailable: Boolean, // Ob verfügbar (unterstützter Carrier)
val operatorCode: String?, // Carrier-Code
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
Diesen Codeblock im schwebenden Fenster anzeigen
Anwendungsbeispiel
MTVerifyApi.checkCoverage(
context = this,
phoneNumber = "6281234567890",
callback = object : CoverageCallback {
override fun onComplete(result: CoverageResult) {
if (result.code == 0) {
if (result.isAvailable) {
// Dienst wird unterstützt
Log.d("MTVerify", "Carrier unterstützt: ${result.operatorCode}")
} else {
// Dienst wird nicht unterstützt
Log.d("MTVerify", "Carrier nicht unterstützt")
}
} else {
// Prüfung fehlgeschlagen
Log.e("MTVerify", "Prüfung fehlgeschlagen: ${result.message}")
}
}
}
)
MTVerifyApi.checkCoverage(
context = this,
phoneNumber = "6281234567890",
callback = object : CoverageCallback {
override fun onComplete(result: CoverageResult) {
if (result.code == 0) {
if (result.isAvailable) {
// Dienst wird unterstützt
Log.d("MTVerify", "Carrier unterstützt: ${result.operatorCode}")
} else {
// Dienst wird nicht unterstützt
Log.d("MTVerify", "Carrier nicht unterstützt")
}
} else {
// Prüfung fehlgeschlagen
Log.e("MTVerify", "Prüfung fehlgeschlagen: ${result.message}")
}
}
}
)
Diesen Codeblock im schwebenden Fenster anzeigen
startAuthentication
Startet den Rufnummernauthentifizierungsablauf.
Methodensignatur
@JvmStatic
fun startAuthentication(
activity: Activity,
countryCode: String,
phoneNumber: String,
callback: AuthenticationCallback? = null
)
@JvmStatic
fun startAuthentication(
activity: Activity,
countryCode: String,
phoneNumber: String,
callback: AuthenticationCallback? = null
)
Diesen Codeblock im schwebenden Fenster anzeigen
Parameter
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| activity | Activity | Ja | Android-Activity-Objekt zur Anzeige der Authentifizierungsoberfläche |
| countryCode | String | Ja | Ländervorwahl |
| phoneNumber | String | Ja | Rufnummer des Nutzers (ohne Ländervorwahl) |
| callback | AuthenticationCallback? | Nein | Authentifizierungs-Callback-Schnittstelle |
Rückgabewert
Keiner
Callback-Ergebnis
Das Authentifizierungsergebnis wird über AuthenticationCallback.onComplete(result: AuthenticationResult) zurückgegeben:
data class AuthenticationResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, -1 bedeutet Fehler, -2 bedeutet vom Nutzer abgebrochen
val token: String?, // Verschlüsselte Authentifizierungsdaten (ein JSON-String mit dem Code, AES-verschlüsselt)
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
data class AuthenticationResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, -1 bedeutet Fehler, -2 bedeutet vom Nutzer abgebrochen
val token: String?, // Verschlüsselte Authentifizierungsdaten (ein JSON-String mit dem Code, AES-verschlüsselt)
val message: String? // Nachricht (Erfolgs- oder Fehlermeldung)
)
Diesen Codeblock im schwebenden Fenster anzeigen
Hinweis: token ist ein verschlüsselter JSON-String im folgenden Format:
{
"version": "1",
"content": {
"code": "Authentifizierungscode",
"state": "Statusparameter",
"appkey": "App-Schlüssel"
}
}
{
"version": "1",
"content": {
"code": "Authentifizierungscode",
"state": "Statusparameter",
"appkey": "App-Schlüssel"
}
}
Diesen Codeblock im schwebenden Fenster anzeigen
Anwendungsbeispiel
MTVerifyApi.startAuthentication(
activity = this,
countryCode = "62",
phoneNumber = "81234567890",
callback = object : AuthenticationCallback {
override fun onComplete(result: AuthenticationResult) {
when (result.code) {
0 -> {
// Authentifizierung erfolgreich
val token = result.token
// Das Token wird zum Einlösen des Ergebnisses verwendet
Log.d("MTVerify", "Authentifizierung erfolgreich: $token")
}
-1 -> {
// Authentifizierung fehlgeschlagen
Log.e("MTVerify", "Authentifizierung fehlgeschlagen: ${result.message}")
}
-2 -> {
// Vom Nutzer abgebrochen
Log.d("MTVerify", "Nutzer hat die Authentifizierung abgebrochen")
}
}
}
}
)
MTVerifyApi.startAuthentication(
activity = this,
countryCode = "62",
phoneNumber = "81234567890",
callback = object : AuthenticationCallback {
override fun onComplete(result: AuthenticationResult) {
when (result.code) {
0 -> {
// Authentifizierung erfolgreich
val token = result.token
// Das Token wird zum Einlösen des Ergebnisses verwendet
Log.d("MTVerify", "Authentifizierung erfolgreich: $token")
}
-1 -> {
// Authentifizierung fehlgeschlagen
Log.e("MTVerify", "Authentifizierung fehlgeschlagen: ${result.message}")
}
-2 -> {
// Vom Nutzer abgebrochen
Log.d("MTVerify", "Nutzer hat die Authentifizierung abgebrochen")
}
}
}
}
)
Diesen Codeblock im schwebenden Fenster anzeigen
Datenmodelle
IPEnvironment
Enum für den Umgebungstyp:
enum class IPEnvironment {
SANDBOX, // Test-/Sandbox-Umgebung
PRODUCTION // Produktionsumgebung
}
enum class IPEnvironment {
SANDBOX, // Test-/Sandbox-Umgebung
PRODUCTION // Produktionsumgebung
}
Diesen Codeblock im schwebenden Fenster anzeigen
InitResult
Initialisierungsergebnis:
data class InitResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg
val message: String? // Nachricht
)
data class InitResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg
val message: String? // Nachricht
)
Diesen Codeblock im schwebenden Fenster anzeigen
CoverageResult
Ergebnis der Abdeckungsprüfung:
data class CoverageResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg
val isAvailable: Boolean, // Ob verfügbar
val operatorCode: String?, // Carrier-Code
val message: String? // Nachricht
)
data class CoverageResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg
val isAvailable: Boolean, // Ob verfügbar
val operatorCode: String?, // Carrier-Code
val message: String? // Nachricht
)
Diesen Codeblock im schwebenden Fenster anzeigen
AuthenticationResult
Authentifizierungsergebnis:
data class AuthenticationResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, -1 bedeutet Fehler, -2 bedeutet vom Nutzer abgebrochen
val token: String?, // Verschlüsseltes Authentifizierungs-Token
val message: String? // Nachricht
)
data class AuthenticationResult(
val code: Int, // Statuscode; 0 bedeutet Erfolg, -1 bedeutet Fehler, -2 bedeutet vom Nutzer abgebrochen
val token: String?, // Verschlüsseltes Authentifizierungs-Token
val message: String? // Nachricht
)
Diesen Codeblock im schwebenden Fenster anzeigen
Callback-Schnittstellen
InitCallback
Initialisierungs-Callback-Schnittstelle:
interface InitCallback {
fun onComplete(result: InitResult)
}
interface InitCallback {
fun onComplete(result: InitResult)
}
Diesen Codeblock im schwebenden Fenster anzeigen
CoverageCallback
Callback-Schnittstelle der Abdeckungsprüfung:
interface CoverageCallback {
fun onComplete(result: CoverageResult)
}
interface CoverageCallback {
fun onComplete(result: CoverageResult)
}
Diesen Codeblock im schwebenden Fenster anzeigen
AuthenticationCallback
Authentifizierungs-Callback-Schnittstelle:
interface AuthenticationCallback {
fun onComplete(result: AuthenticationResult)
}
interface AuthenticationCallback {
fun onComplete(result: AuthenticationResult)
}
Diesen Codeblock im schwebenden Fenster anzeigen
Vollständiges Beispiel
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// 1. Logging aktivieren (optional)
MTVerifyApi.setLogEnable(true)
// 2. Das SDK initialisieren
MTVerifyApi.init(
context = this,
appkey = "your_app_key",
environment = IPEnvironment.SANDBOX,
callback = object : InitCallback {
override fun onComplete(result: InitResult) {
if (result.code == 0) {
// Initialisierung erfolgreich; Sie können nun andere Funktionen verwenden
checkCoverage()
}
}
}
)
}
private fun checkCoverage() {
// 3. Die Abdeckung prüfen
MTVerifyApi.checkCoverage(
context = this,
phoneNumber = "6281234567890",
callback = object : CoverageCallback {
override fun onComplete(result: CoverageResult) {
if (result.isAvailable) {
// 4. Falls unterstützt, Authentifizierung durchführen
startAuthentication()
}
}
}
)
}
private fun startAuthentication() {
// 5. Authentifizierung durchführen
MTVerifyApi.startAuthentication(
activity = this,
countryCode = "62",
phoneNumber = "81234567890",
callback = object : AuthenticationCallback {
override fun onComplete(result: AuthenticationResult) {
if (result.code == 0) {
// Authentifizierung erfolgreich; das Token verarbeiten
handleToken(result.token)
}
}
}
)
}
private fun handleToken(token: String?) {
// Die API aufrufen, um das eingelöste Token zu verarbeiten
}
}
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// 1. Logging aktivieren (optional)
MTVerifyApi.setLogEnable(true)
// 2. Das SDK initialisieren
MTVerifyApi.init(
context = this,
appkey = "your_app_key",
environment = IPEnvironment.SANDBOX,
callback = object : InitCallback {
override fun onComplete(result: InitResult) {
if (result.code == 0) {
// Initialisierung erfolgreich; Sie können nun andere Funktionen verwenden
checkCoverage()
}
}
}
)
}
private fun checkCoverage() {
// 3. Die Abdeckung prüfen
MTVerifyApi.checkCoverage(
context = this,
phoneNumber = "6281234567890",
callback = object : CoverageCallback {
override fun onComplete(result: CoverageResult) {
if (result.isAvailable) {
// 4. Falls unterstützt, Authentifizierung durchführen
startAuthentication()
}
}
}
)
}
private fun startAuthentication() {
// 5. Authentifizierung durchführen
MTVerifyApi.startAuthentication(
activity = this,
countryCode = "62",
phoneNumber = "81234567890",
callback = object : AuthenticationCallback {
override fun onComplete(result: AuthenticationResult) {
if (result.code == 0) {
// Authentifizierung erfolgreich; das Token verarbeiten
handleToken(result.token)
}
}
}
)
}
private fun handleToken(token: String?) {
// Die API aufrufen, um das eingelöste Token zu verarbeiten
}
}
Diesen Codeblock im schwebenden Fenster anzeigen
Hinweise
- Initialisierungsreihenfolge: Sie müssen zuerst die Methode
init()aufrufen, um das SDK zu initialisieren, bevor Sie andere Funktionen verwenden können. - Thread-Sicherheit: Alle API-Methoden können im Hauptthread aufgerufen werden, und auch die Callbacks werden im Hauptthread ausgeführt.
- Berechtigungsanforderungen: Stellen Sie sicher, dass die App die erforderlichen Netzwerkberechtigungen angefordert hat.
- Token-Entschlüsselung: Das nach erfolgreicher Authentifizierung zurückgegebene Token ist verschlüsselt und muss mit der entsprechenden Entschlüsselungsmethode verarbeitet werden.
- Log-Steuerung: Es wird empfohlen, die Log-Ausgabe in der Produktionsumgebung zu deaktivieren, um Leistung und Sicherheit zu verbessern.
Versionsinformationen
- SDK-Version: 1.0.1
