Lite SDK (Enregistrement Android)

Nous recommandons d'utiliser le SDK Seamless Android pour une expérience d'intégration fluide. Cette option offre une solution de paiement flexible avec des composants d'interface utilisateur (UI) pré-construits et des options de personnalisation.

• Ont besoin d'une implémentation rapide avec des exigences de personnalisation minimales
• Veulent se concentrer principalement sur l'enregistrement de méthodes de paiement
• Préfèrent une interface utilisateur prête à l'emploi qui gère le flux d'enregistrement

Le Lite SDK comprend des fonctionnalités de base telles que :

• Composants d'interface utilisateur d'enregistrement pré-construits
• Traitement de l'enregistrement de carte
• Gestion de base du statut d'enregistrement
• Gestion essentielle des erreurs

Pour les commerçants nécessitant des fonctionnalités plus avancées comme plusieurs méthodes de paiement, une interface utilisateur personnalisée ou une prévention avancée de la fraude, veuillez considérer l'utilisation de notre Full SDK.

Prérequis

Avant de commencer l'intégration du SDK Android de Yuno, assurez-vous que votre projet répond aux exigences techniques. De plus, les pré-requis suivants doivent être en place :

• Vous devez disposer d'un compte Yuno actif
• Vous avez besoin de vos identifiants API Yuno (public-api-key), que vous pouvez obtenir dans la  Section Développeurs du tableau de bord Yuno
• Avant d'enregistrer une méthode de paiement, vous devez d'abord créer un client en utilisant le endpoint Créer un client

Étape 1 : Créer un client

Créez un client dans le système de Yuno en utilisant le endpoint  Créer un client  avant d'enregistrer des méthodes de paiement. Cet endpoint retournera un customer_id que vous utiliserez pour associer les méthodes de paiement enregistrées au client spécifique.

L'endpoint retournera une customer_session que vous devrez utiliser lors de l'appel des méthodes d'enregistrement.

Étape 2 : Inclure la bibliothèque dans votre projet

Ajoutez le Lite SDK de Yuno à votre projet Android :

Ajouter le Dépôt

Ajoutez le dépôt Maven de Yuno à la configuration Gradle de votre projet :

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

Incluez le code suivant dans le fichier build.gradle pour ajouter la dépendance du SDK Yuno à l'application :

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Permissions

Le SDK Yuno inclut la permission INTERNET par défaut, qui est requise pour effectuer des requêtes réseau.

<uses-permission android:name="android.permission.INTERNET" />

Étape 3 : Initialiser le SDK avec la clé publique

Initialisez le SDK :

1. Obtenez votre clé d'API publique à partir du tableau de bord Yuno
2. Créez une classe d'application personnalisée si vous ne l'avez pas encore fait.
3. Dans la méthode onCreate() de votre classe d'application, appelez Yuno.initialize() avec votre clé API :

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config: YunoConfig,
    )
  }
}

Utiliser la classe de données YunoConfig pour personnaliser le comportement du SDK. Incluez cette configuration lors de l'appel à Yuno.initialize(). Les options disponibles sont :

classe de données YunoConfig(
    val cardFlow : CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled : Boolean = false,
    val keepLoader : Boolean = false,
    val cardFormDeployed : Boolean = false,
    val language : YunoLanguage? = null,
    val styles : YunoStyles? = null
)

Le tableau suivant décrit chaque option de personnalisation :

Vous devez également mettre à jour votre manifeste pour utiliser votre application :

<application android:name=".CustomApplication"></application>

Étape 4 : Enregistrer une nouvelle méthode de paiement

Le processus d'enregistrement est un flux en deux étapes. Tout d'abord, initialisez le processus pour configurer les composants nécessaires. Ensuite, démarrez le flux d'interface utilisateur pour permettre à l'utilisateur d'enregistrer une méthode de paiement.

4.1 Initialiser le processus d'enregistrement

Appelez la fonction initEnrollment dans la méthode onCreate de votre activité pour préparer votre application à gérer le flux d'enregistrement. Il s'agit d'une étape de configuration obligatoire requise par le système d'exploitation Android pour enregistrer le contrat qui permet au SDK de renvoyer le statut final de l'enregistrement à votre application.

fun ComponentActivity.initEnrollment(
 callbackEnrollmentState: ((String?) -> Unit)? = null
)

4.2 Démarrer le flux d'enregistrement

Appelez la fonction startEnrollment pour lancer l'interface utilisateur et commencer l'enregistrement d'une nouvelle méthode de paiement. Vous pouvez appeler cette méthode à tout moment après l'exécution de initEnrollment , par exemple lorsqu'un utilisateur appuie sur un bouton "Enregistrer un nouveau mode de paiement".

fun Activity.startEnrollment(
    customerSession: String,
 countryCode: String,
    showEnrollmentStatus: Boolean = true,
 callbackEnrollmentState: ((String?) -> Unit)? = null,
    requestCode: Int
)

Le tableau suivant décrit les paramètres de startEnrollment :

État de l'Enregistrement par Rappel

Le champ callbackEnrollmentState est une fonction qui retourne le statut actuel du processus d'enregistrement. Fournissez cette fonction uniquement si vous souhaitez suivre le statut de l'enregistrement.

Utilisez l'endpoint  AppCompatActivity.enrollmentStatus() pour vérifier l'état actuel de l'enregistrement à tout moment. Cette fonction est facultative et accepte les mêmes paramètres que startEnrollment. Le bloc de code suivant montre la signature de la fonction :

fun AppCompatActivity.enrollmentStatus(
    customerSession: String,
 countryCode: String,
    showEnrollmentStatus: Boolean = false,
 callbackEnrollmentState: ((String?) -> Unit)? = null,
)

📘

Fonction Facultative

L'utilisation de la fonction enrollmentStatus est facultative. Ce n'est pas une exigence pour compléter le processus d'enregistrement.  En savoir plus

🚧

Remplacement du rappel

Si vous fournissez un nouveau Rappel lors de l'appel de la fonction enrollmentStatusil remplacera le Rappel que vous avez défini lors de l'appel de la fonction initEnrollment.

Le bloc de code suivant montre les états possibles :

const val ENROLLMENT_STATE_SUCCEEDED = "SUCCEEDED"
const val ENROLLMENT_STATE_FAIL = "FAIL"
const val ENROLLMENT_STATE_PROCESSING = "PROCESSING"
const val ENROLLMENT_STATE_REJECT = "REJECT"
const val ENROLLMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val ENROLLMENT_STATE_CANCELED_BY_USER = "CANCELED"

Le tableau suivant fournit des informations supplémentaires sur les états possibles :

Utilisation de la méthode OnActivityResult du SDK

❗️

Méthode Dépréciée

Le champ onActivityResult est une solution dépréciée. Si vous effectuez une nouvelle intégration Android, Yuno recommande d'utiliser le contrat initEnrollment() , qui suit les meilleures pratiques de Google.

La méthode onActivityResult est automatiquement invoquée lorsqu'une activité renvoie un résultat. Vous pouvez utiliser cette option pour exécuter des actions chaque fois que le statut d'enregistrement change. Suivez ces étapes pour traiter le résultat de l'enregistrement :

📘

Utilisation du Code de Requête par Défaut

Si vous utilisez la méthode onActivityResult mais n'avez pas informé de requestCode lors de l'appel à  startEnrollment dans les requêtes de  l'Étape 3, vous devez utiliser le YUNO_ENROLLMENT_REQUEST_CODE fournie par Yuno.

1. Remplacez la méthode onActivityResult . Cela garantit que les appels hiérarchiques sont respectés.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
}

2. Vérifiez si le requestCode correspond à YUNO_ENROLLMENT_REQUEST_CODE. Comme vous exécutez Yuno dans votre application, vous pouvez importer YUNO_ENROLLMENT_REQUEST_CODE pour l'utiliser.

if (requestCode == YUNO_ENROLLMENT_REQUEST_CODE) {
}

3. Si le requestCode correspond, gérez le résultat de l'enregistrement. Extrayez l'état de l'enregistrement à l'aide de la clé YUNO_ENROLLMENT_RESULT fournie par la bibliothèque Yuno. Créez une fonction onEnrollmentStateChange pour gérer les changements d'état.

onEnrollmentStateChange(data ?.getStringExtra(YUNO_ENROLLMENT_RESULT))

Le bloc de code suivant montre un exemple de code pour utiliser la méthode OnActivityResult afin d'exécuter des fonctions lorsque le statut d'enregistrement change :

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == YUNO_ENROLLMENT_REQUEST_CODE) {
        val enrollmentState = data?.getStringExtra(YUNO_ENROLLMENT_RESULT)
        onEnrollmentStateChange(enrollmentState)
    }
}

fun onEnrollmentStateChange(enrollmentState: String?) {
    when (enrollmentState) {
        "SUCCEEDED" -> {
        }
        "FAIL" -> {
        }
    }
}

Étape 5 : Obtenir le statut d'enregistrement

Appelez la fonction initEnrollment dans la méthode onCreate de l'activité pour enregistrer un rappel afin d'obtenir l'état final de l'enregistrement.

Fonctionnalités Complémentaires

Le SDK Android de Yuno fournit des services et des configurations supplémentaires que vous pouvez utiliser pour améliorer l'expérience de vos clients. Utilisez la personnalisation du SDK pour changer l'apparence du SDK afin qu'il corresponde à votre marque ou pour configurer le loader.

styles

Avec l'option de personnalisation styles , vous pouvez définir des styles visuels globaux via un objet YunoStyles . Il vous permet d'appliquer une image de marque cohérente dans tout le SDK en personnalisant l'apparence des boutons et la typographie.

classe de données YunoStyles(
    val buttonStyles: YunoButtonStyles? = null,
    val fontFamily: FontFamily? = null
)

Le champ YunoButtonStyles vous permet de définir des paramètres spécifiques pour l'apparence des boutons :

data class YunoButtonStyles(
    val backgroundColor : Couleur ? = null,
    val contentColor : Couleur ? = null,
    val cornerRadius : Dp ? = null,
    val elevation : Dp ? = null,
    val padding : Dp ? = null,
    val fontFamily : FontFamily ? = null,
    val fontSize : TextUnit ? = null,
    val fontStyle : FontStyle ? = null
)

Utilisez l'endpoint  YunoConfig , décrite à l'Étape 3, pour utiliser l'option de personnalisation des styles .

Loader

La fonctionnalité du loader est contrôlée par le paramètre keepLoader dans la classe de données YunoConfig qui est documentée en ligne dans la section de configuration du SDK ci-dessus.

Options de rendu

Vous pouvez choisir entre deux options de rendu de formulaire de carte. Les captures d'écran suivantes montrent la différence entre cardFormType ONE_STEP  et  STEP_BY_STEP:

Personnalisation du SDK

Vous pouvez modifier l'apparence du SDK pour qu'elle corresponde à votre marque. Pour plus d'informations, consultez la page de personnalisation du SDK.

📘

Application Démo

En plus des exemples de code fournis, vous pouvez consulter le dépôt Yuno pour l'implémentation complète des SDK Android de Yuno.

Mode Rendu (Enregistrement)

Le mode rendu du SDK Yuno vous permet d'intégrer le flux d'enregistrement avec un contrôle total de l'interface utilisateur tout en conservant la validation et la logique du SDK. Le SDK renvoie des instances de Fragment Android que vous pouvez afficher à la fois dans Jetpack Compose (via AndroidView) et dans les mises en page XML traditionnelles.

Fonction principale : startEnrollmentRender

fun Activity.startEnrollmentRender(
    customerSession: String,
 countryCode: String,
    submitButton: Boolean = false,
    coroutineScope: CoroutineScope,
    listener: YunoEnrollmentRenderListener
): YunoEnrollmentFragmentController

Paramètres

Valeur de Retour

Renvoie un YunoEnrollmentFragmentController pour contrôler le flux d'enregistrement (par exemple, soumettre des formulaires).

Exemple d'utilisation

class EnrollmentActivity : Activity() {

    private lateinit var fragmentController: YunoEnrollmentFragmentController

    private fun initializeEnrollment() {
        fragmentController = startEnrollmentRender(
            customerSession = "your_customer_session_id",
            countryCode = "US",
            submitButton = false,
            coroutineScope = lifecycleScope,
            listener = enrollmentRenderListener
        )
    }
}

Interface : YunoEnrollmentRenderListener

Implémentez cette interface pour recevoir les fragments et événements d'enregistrement.

interface YunoEnrollmentRenderListener {
    fun showView(fragment: Fragment, needSubmit: Boolean)
    fun returnStatus(resultCode: Int, paymentStatus: String)
    fun loadingListener(isLoading: Boolean)
}

showView(fragment : Fragment, needSubmit : Boolean)

• Reçoit le fragment à afficher dans votre conteneur d'interface utilisateur
• needSubmit indique si vous devez afficher votre propre bouton de soumission (lorsque submitButton = false)

Exemple (XML) :

override fun showView(fragment: Fragment, needSubmit: Boolean) {
    supportFragmentManager.beginTransaction()
        .replace(R.id.enrollment_container, fragment)
        .commit()

    clientSubmitButton.isVisible = needSubmit
    if (needSubmit) {
        clientSubmitButton.setOnClickListener { fragmentController.submitForm() }
    }
}

returnStatus(resultCode : Int, paymentStatus : String)

• Événement de statut d'enregistrement final. Utilisez-le pour notifier l'utilisateur du succès ou de l'échec.

loadingListener(isLoading : Boolean)

• Rappel d'état de chargement pour afficher/masquer les spinners et désactiver/activer l'interface utilisateur

override fun loadingListener(isLoading: Boolean) {
    progressBar.isVisible = isLoading
    clientSubmitButton.isEnabled = !isLoading
}

Interface : YunoEnrollmentFragmentController

Retourné par startEnrollmentRender pour contrôler le flux d'enregistrement.

interface YunoEnrollmentFragmentController {
    fun submitForm()
}

val fragmentController = startEnrollmentRender(
    customerSession = "your_customer_session_id",
 countryCode "US",
    submitButton = false,
    coroutineScope = lifecycleScope,
    listener = enrollmentRenderListener
)

3. Contrôlez le flux (soumettez-le si nécessaire) :

fragmentController.submitForm()

Avantages du Mode Rendu

Flexibilité de l'interface utilisateur

• Compatible avec Compose (via AndroidView) et XML
• Contrôle total sur où et comment les vues sont affichées.
• Facile à adapter au système de conception de votre application.

Contrôle du Flux

• Délai de soumission personnalisé à l'aide de submitForm()

Considérations Importantes

• Liez la coroutineScope au cycle de vie de votre Activité/Fragment (par exemple,  lifecycleScope)
• Lorsque  needSubmit = true, affichez votre propre bouton de soumission et appelez  submitForm()
• Dans Compose, placez le fragment dans un conteneur AndroidView .