App-to-App integration

1. Introduction et vue d'ensemble

1.1 Qu'est-ce que l'intégration App-to-App ?

L'intégration App-to-App est la solution qui permet à votre application (système de caisse ou POS) de communiquer de manière sécurisée avec l'application de paiement Market Pay sur le même appareil.

Cela est possible grâce à la Communication Inter-Processus (IPC). Dans l'environnement Android, l'IPC permet la communication entre deux applications distinctes fonctionnant simultanément sur le même appareil.

1.2 Pourquoi utiliser le SDK Market Pay ?

L'intégration du SDK Market Pay est le moyen le plus simple d'établir une communication App-to-App. L'objectif principal du SDK est de masquer les détails complexes de bas niveau de l'IPC Android, tels que l'AIDL (Android Interface Definition Language) et la connectivité Binder.

Au lieu de gérer la sérialisation des données brutes et la liaison des processus, le SDK fournit une interface Client claire (un objet Java simple ou POJO). Cette interface permet à vos développeurs d'initier des actions comme le paiement ou la connexion via des appels de méthodes intuitifs, tels que sendPaymentRequest().

Le SDK inclut également des fonctionnalités robustes pour la gestion des messages et des états :

• Conversion Inter-protocole : Convertit automatiquement les messages entre différents standards (ex: Nexo Retailer Protocol) selon les besoins.

• Gestion de la connectivité : Gère la connexion, la déconnexion et la reconnexion au service de l'application de paiement.

• Retours asynchrones : Utilise un Interceptor pour livrer les réponses de transaction et un EventObserver pour notifier votre application des changements d'état (ex: IdleTransactionState, PaymentTransactionState).

1.3 Liste des prérequis

Avant de commencer l'installation du SDK, assurez-vous que les conditions suivantes sont remplies :

2. Configuration : Installation et initialisation du SDK

2.1 Étape 1 : Ajouter la dépendance du SDK

Placez le fichier .aar fourni (ex: client-clientRelease-0.0.8_cc9d51b.aar) dans le dossier libs de votre module.

Ajoutez la ligne de dépendance dans le fichier build.gradle de votre module :

dependencies {
    // ... autres dépendances
    implementation files('libs/client-clientRelease-0.X.X.aar')
}

2.2 Étape 2 : Configurer et construire le Client

La ClientFactory est utilisée une seule fois, généralement au démarrage de votre application (dans votre classe Application ou votre Activity principale), pour établir la connexion et configurer les gestionnaires.

// 1. Démarrer la chaîne de configuration
val clientInstance = ClientFactory
    .bindConfiguration( 
        // 2. CONFIGURER L'APP DE DESTINATION (L'application de paiement)
        SDKConfiguration.defaultConfiguration(
            clientApplicationInfo = PackageInfo(
                applicationName = applicationInfo.name, // Nom de votre application 
                applicationPackage = packageName // Nom du package de votre application
            )
        )
    )
    .bindContext(context = applicationContext)
    .bindProtocolConfiguration(
        // 3. CONFIGURER LE PROTOCOLE (Exemple Nexo Retailer Protocol v3)
        RetailerConfiguration(saleID = "Communicator_SALE")
    )
    .bindInterceptor { message: DomainMessage -> 
        // 4. GESTIONNAIRE DE RÉPONSES AUX MESSAGES (Voir Section 3.2)
        // C'est ici qu'arrivent toutes les réponses (Succès, Erreur, etc.)
        when (message) {
            is SuccessRetailerLoginResponse -> { /* Gérer succès connexion */ }
            is ErrorRetailerLoginResponse -> { /* Gérer échec connexion */ }
        }
    }
    .bindEventObserver { event: ObservableEvent -> 
        // 5. GESTIONNAIRE D'ÉVÉNEMENTS DE L'APPLICATION (Voir Section 3.3)
        // Gère les changements d'état (Idle, Traitement) et la mise au premier plan.
        when (event) {
            is ObservableEvent.TransactionStateChanged -> { 
                // Gérer les changements d'état et ramener votre app au premier plan
            }
            is ObservableEvent.ServerEvent -> { 
                // Gérer les événements serveur généraux
            }
        }
    }
    .build() // 6. Finaliser et connecter

3. Utilisation principale : Envoi de requêtes et gestion des réponses

3.1 Spécificités du protocole Nexo Retailer

Chaque session de communication doit commencer par une requête RetailerLoginRequest. Elle doit être déclenchée dans les cas suivants :

• Mise à jour ou redémarrage de l'application de paiement.

• Redémarrage de votre application.

• Perte de connexion entre les applications.

• Envoi d'une requête RetailerLogoutRequest.

Une nouvelle procédure de connexion est nécessaire pour instancier la session, sinon vos requêtes seront considérées comme non autorisées.

3.1 Envoi de requêtes (Interface Client)

L'instance de l'interface Client renvoyée par ClientFactory::build() est votre outil de communication principal. Toutes les méthodes sont des fonctions suspendues et doivent être appelées depuis une portée de coroutine.

Note sur le TransactionID : Il doit comporter 35 caractères maximum. Si vous utilisez un UUID, supprimez les tirets ("-").

4. Gestion des états et des événements

4.1 L'EventObserver (Changements d'état)

Utilisez bindEventObserver pour surveiller le statut opérationnel de l'application de paiement et gérer l'interface utilisateur de votre application.

4.2 Mise au premier plan (BringToForeground)

La fonction bringToForeground(MainActivity::class.java) est responsable du "rappel" de votre application au premier plan après un changement d'état.

• Exemple : Vous souhaitez afficher une publicité ou des détails personnalisés pendant le traitement au lieu de l'icône de chargement de l'application de paiement. Utilisez le chemin PaymentTransactionState.

.bindEventObserver { event: ObservableEvent -> 
    when (event) {
        is ObservableEvent.TransactionStateChanged -> when (event.state) {
            // Ramener l'app au premier plan à la fin du paiement
            is IdleTransactionState -> bringToForeground(MainActivity::class.java) 
            // Optionnel : Ramener l'app au premier plan au début du paiement
            is PaymentTransactionState -> bringToForeground(MainActivity::class.java)
            else -> { /* Ignorer les autres états */ } 
        }
        is ObservableEvent.ServerEvent -> Logger.d("Nouvel événement serveur") 
    } 
}

5. Annexe : Règles ProGuard

Si votre projet utilise l'offuscation via R8/ProGuard, assurez-vous d'ajouter les règles suivantes à votre fichier proguard-rules.pro :

-keep class pl.novelpay.** { *; } 
-dontwarn pl.novelpay.** -keep class org.koin.** { *; } 
-keep class androidx.lifecycle.** { *; } 
-keep class com.jakewharton.threetenabp.** { *; } 
-dontwarn com.google.gson.annotations.SerializedName
-dontwarn javax.xml.stream.**
-keepattributes InnerClasses,Signature,RuntimeVisible*Annotations,EnclosingMethod
-keep class kotlin.Metadata { *; } 
-keep class org.simpleframework.** { *; } 
-keepattributes Annotation