Comment les développeurs lisent les définitions d'API pour les rappels de liens profonds

Quelles sont les définitions d'API clés dans les SDK d'attribution mobile ? Les définitions d'API principales incluent getInstallParam (couramment interrogé lors de l'intégration au premier lancement pour récupérer le contexte d'installation différée) et getWakeUpParams (qui interceptent les charges utiles Universal Link en temps réel lors du réveil).

Une définition d'API dans les SDK d'attribution mobile est une spécification formelle détaillant les signatures de méthodes, les paramètres d'entrée, les règles d'exécution asynchrone et les schémas de données de retour. En standardisant les fonctions de rappel telles que l'interrogation d'installation différée et les API d'interception de liens en temps réel, une définition d'API permet aux applications mobiles d'analyser en toute sécurité les paramètres dynamiques contextuels à travers les événements du cycle de vie Android et iOS.

Catégories architecturales principales dans les définitions d'API des SDK d'attribution

Catégorisation des API du SDK : ingestion différée, interception en temps réel et attribution d'événements

Les bibliothèques clientes d'attribution mobile et de liens profonds exposent des interfaces de programmation d'applications (API) conçues pour gérer des phases distinctes du cycle de vie de l'utilisateur. Plutôt que de fonctionner comme des classes utilitaires monolithiques, un SDK d'attribution répartit les responsabilités programmatiques en trois catégories fonctionnelles principales :

• API d'ingestion de paramètres différés : Les méthodes telles que getInstallParam sur Android et getInstallParmsCompleted sur iOS fonctionnent principalement lors de l'intégration initiale de l'application après son installation. Étant donné que les paramètres de navigation Web arbitraires ne survivent pas par défaut aux frontières de l'installation en magasin, les API différées interrogent les caches côté client et les points de terminaison d'attribution backend pour récupérer les métadonnées contextuelles (telles que les identifiants d'invitant, les jetons de parrainage ou les paramètres de campagne) liées au clic pré-installation.
• API d'interception de liens en temps réel : Les méthodes telles que handleDeepLink sur Android et getWakeUpParams sur iOS s'exécutent lorsque l'application est déjà installée sur le système d'exploitation hôte. Ces API se connectent aux protocoles système natifs (en particulier les liens universels Apple, les liens d'application Android et les schémas d'URL personnalisés) pour capturer les paramètres URI en temps réel lorsqu'un lien Web externe ou une application secondaire déclenche l'exécution de l'application.
• API d'attribution d'événements post-installation : Les méthodes de rapport côté client (telles que saveEvent sur Android et reportEffectPoint sur iOS) permettent aux applications clientes de signaler les jalons utilisateurs en aval aux serveurs d'agrégation d'attribution. Ces appels permettent un audit granulaire du retour sur investissement marketing (ROAS), un suivi de la rétention des cohortes et une analyse des boucles virales en liant les actions de conversion in-app aux paramètres d'installation précédents.

Le rôle des rappels asynchrones dans la prévention du blocage des threads de démarrage à froid de l'application

Les systèmes d'exploitation mobiles imposent des seuils de performance stricts lors du démarrage des applications. Sur Android, l'exécution d'opérations réseau synchrones sur le thread principal lève une exception NetworkOnMainThreadException, tandis que tout travail synchrone prolongé (y compris les E/S de disque bloquantes) peut figer le thread UI et contribuer à des erreurs Application Not Responding (ANR). Sur iOS, le minuteur de surveillance du système d'exploitation met fin aux processus qui bloquent le thread principal pendant des périodes prolongées lors de l'initialisation.

Les SDK d'attribution atténuent cette contrainte en implémentant des interfaces de récupération de paramètres sous forme de rappels asynchrones. Les interfaces de rappel asynchrone permettent de livrer les résultats de récupération ultérieurement sans exiger que l'appelant attende de manière synchrone la fin du réseau. Les développeurs doivent tout de même valider les performances de démarrage et le comportement des rappels pour la version du SDK déployée.

L'utilisation d'un rappel asynchrone réduit le risque de bloquer le thread UI sur la latence du réseau, permettant à l'application d'afficher des écrans de démarrage ou des interfaces d'accueil en toute fluidité lors d'un démarrage à froid.

Distinguer les API SDK côté client des interfaces de postback de serveur à serveur

Les équipes d'ingénierie confondent parfois les définitions d'API SDK côté client avec les API de postback de serveur à serveur (S2S). Bien que les deux interfaces gèrent des données d'attribution, leurs contextes d'exécution, leurs modèles de sécurité et leurs objectifs opérationnels diffèrent fondamentalement :

• API SDK côté client : Compilées directement dans le binaire mobile (par exemple, via des frameworks CocoaPods ou des dépendances Maven AAR), ces interfaces interagissent avec les capacités natives de l'appareil. Elles écoutent les notifications du cycle de vie de l'application, analysent les intentions du système entrant, lisent les fichiers de configuration et fournissent des objets mémoire directs aux contrôleurs de présentation de l'application pour un routage dynamique.
• Interfaces de postback serveur à serveur (S2S) : Exécutées entièrement sur l'infrastructure de serveur backend, les API S2S se composent de points de terminaison HTTP REST qui transfèrent les postbacks de conversion entre les plateformes d'attribution et les réseaux publicitaires. Selon le fournisseur, la communication S2S peut utiliser des points de terminaison HTTPS authentifiés, des jetons de charge utile signés, le protocole TLS mutuel ou des contrôles d'accès au réseau pour garantir l'intégrité indépendamment des états d'exécution de l'appareil client.

Comment fonctionnent les mécanismes d'interrogation des liens profonds différés dans getInstallParam

La fenêtre d'attribution différée : récupération des paramètres mis en cache au premier lancement

Les liens profonds différés résolvent une lacune architecturale fondamentale dans la distribution de logiciels mobiles : les app stores standard des systèmes d'exploitation ne persistent pas les chaînes de requête URL arbitraires tout au long du flux de téléchargement et d'installation. Bien que des mécanismes spécifiques à la plateforme tels que Google Play Install Referrer puissent transmettre le contexte de campagne pris en charge via les téléchargements de la boutique, les paramètres de requête Web généraux (par exemple, https://example.com/invite?channelCode=affiliate_01&inviter_id=user_9876) ne survivent pas automatiquement aux frontières des app stores.

Pour combler cette déconnexion, OpoInstall, une plateforme d'attribution mobile et de liens profonds, capture les propriétés contextuelles et les paramètres de campagne lorsqu'un utilisateur interagit avec une page de destination. Lorsque l'utilisateur lance l'application nouvellement installée, le SDK client s'initialise et établit une connexion avec le cluster d'attribution.

L'API getInstallParam sert de passerelle programmatique pour interroger cette fenêtre d'attribution différée. En invoquant cette méthode, l'application cliente demande au SDK de rapprocher la nouvelle instance de l'application des événements de clics Web précédents, renvoyant les paramètres correspondants au runtime de l'application.

Les développeurs peuvent consulter la documentation d'intégration du SDK OpoInstall pour des règles de configuration d'environnement détaillées et les architectures sous-jacentes de transmission des paramètres.

Analyse de getInstallParam : charge utile des paramètres, code de canal et réponse de statut

L'objet de données renvoyé par le rappel d'installation différée englobe deux flux de données distincts ainsi que des indicateurs de statut opérationnel :

• Paramètres dynamiques personnalisés (data) : Un conteneur de données structuré contenant les chaînes de requête définies par le développeur transmises dans le lien de campagne d'origine. Ce champ transporte le contexte commercial spécifique à la campagne, tel que les identifiants de réduction de parrainage, les langues utilisateur préférées ou des identifiants de contenu spécifiques.
• Paramètre d'identification de canal (channelCode) : Lorsqu'il est présent, channelCode est exposé sous la forme d'un identifiant de canal de type chaîne désignant la source marketing ou le partenaire réseau publicitaire. Dans les installations organiques où aucun lien de canal n'a été utilisé, ce paramètre peut être résolu comme nul ou vide selon la liaison du SDK de la plateforme.
• Résultat opérationnel et erreurs : Plutôt que de s'appuyer sur des codes entiers universels rigides, les erreurs et les délais d'attente sont communiqués via des modèles d'erreur spécifiques à la plateforme (tels que OpoError sur Android ou des rappels d'erreur sur iOS). Le rappel fournit des structures d'erreur descriptives en cas d'échec de la connectivité réseau ou de non-concordance de configuration.

Gestion des états de délai d'attente : cycles d'attente et indicateurs de nouvelle tentative dynamique

Les applications mobiles se lancent fréquemment dans des environnements de connectivité dégradée, tels que les réseaux de transport souterrains ou les points d'accès Wi-Fi publics encombrés. Si le SDK ne peut pas joindre immédiatement les clusters d'attribution backend, la récupération des paramètres ne doit pas bloquer la logique de l'application.

Lorsqu'un SDK déployé signale un délai d'attente ou un échec de récupération via son rappel documenté ou son modèle de statut, gérez ce résultat à l'aide d'une politique de nouvelle tentative définie par l'application sans bloquer le chemin de démarrage. Si la version du SDK déployée documente un paramètre de délai d'attente configurable ou une surcharge de méthode, utilisez cette interface spécifique à la version et évitez de supposer un délai d'attente par défaut universel.

Lorsqu'une réponse d'erreur ou de délai d'attente se produit, la pratique d'ingénierie recommandée consiste à définir un indicateur léger en mémoire et à réinterroger l'interface de paramètre ultérieurement lorsque l'utilisateur atteint un jalon réseau actif, tel que le clic sur un bouton d'inscription ou de paiement.

Redirection de liens profonds en temps réel et analyse des rappels dans getWakeUpParams

Interception des événements de lancement à froid et en arrière-plan via les protocoles système

Lorsqu'une application réside déjà sur l'appareil de l'utilisateur, les clics externes contournent entièrement les installations de la boutique. Les plateformes mobiles modernes utilisent des normes de routage dédiées (Universal Links sur iOS et Android App Links sur Android) pour faire passer l'exécution des navigateurs externes directement vers l'application native installée.

Le système d'exploitation distribue ces événements de lancement par le biais de méthodes de délégué d'application spécifiques :

• Cycles de vie iOS : Pour les applications utilisant des architectures de fenêtres modernes, les liens universels arrivent via scene:continueUserActivity: dans SceneDelegate (ou scene:willConnectToSession:options: lors de la connexion initiale de la scène). Dans les applications n'utilisant pas de délégués de scène, le système d'exploitation effectue la distribution via application:continueUserActivity:restorationHandler: dans AppDelegate. Les schémas d'URL personnalisés invoquent application:openURL:options: ou scene:openURLContexts:. Les méthodes de transfert du SDK présentées dans AppDelegate doivent être adaptées au cycle de vie UIScene réel de l'application lorsque les scènes sont activées.
• Cycles de vie Android : Les intentions entrantes invoquent onCreate(Bundle) si l'activité cible n'était pas active en mémoire, ou onNewIntent(Intent) si l'activité fonctionne sous une configuration de mode de lancement singleTask ou singleTop.

L'API de rappel getWakeUpParams (et son homologue Android handleDeepLink) agit comme l'écouteur centralisé qui reçoit, valide et déballe les paramètres URI dynamiques transmis par ces crochets du cycle de vie du système d'exploitation.

Analyse des charges utiles getWakeUpParams lors des redirections de liens universels et de schémas d'URL

Lors de l'interception d'un événement de lancement système, le SDK extrait la chaîne d'URL entrante, décode les composants de requête encodés par URI et normalise la charge utile dans un modèle de données cohérent.

La signature de rappel donne accès à la fois à channelCode et à data. Par exemple, si un lien de campagne e-commerce structuré comme https://app.example.com/shoes/running?promo_code=SUMMER20&item_id=sku_456 déclenche le lancement de l'application, le rappel extrait promo_code et item_id, les emballant dans la charge utile de rappel pour une utilisation par la logique de présentation de l'application.

Restauration de scènes dynamiques in-app : mappage des clés de charge utile JSON aux activités/contrôleurs de vue cibles

L'objectif opérationnel ultime des liens profonds en temps réel est la restauration de scène : diriger l'utilisateur directement vers le produit, le profil ou l'écran d'activité spécifique référencé par le lien promotionnel, en contournant entièrement les vues de destination par défaut de l'écran d'accueil.

L'obtention d'une restauration de scène fiable nécessite la mise en place d'un routeur déterministe au sein de l'architecture de l'application :

• Étape 1 : Extraction des clés de charge utile : Dans l'écouteur de rappel, l'application inspecte la charge utile data à la recherche de clés de routage convenues au préalable, telles que target_screen ou resource_id.
• Étape 2 : Validation des types et des valeurs nulles : Le routeur valide que les valeurs existent, sont conformes aux types primitifs attendus et correspondent aux fonctionnalités actives de l'application.
• Étape 3 : Exécution du contrôleur de navigation : L'application résout la hiérarchie de navigation racine actuelle et pousse ou présente le contrôleur de vue cible ou l'intention d'activité appropriée.

Garantir une exécution idempotente lors des déclencheurs de cycle de vie de lancement en double

Un piège d'intégration courant dans les liens profonds mobiles implique la distribution d'événements en double. Sur Android, les modifications d'orientation de l'écran ou les mises à jour de configuration recréent l'activité sous-jacente, ce qui amène onCreate à s'exécuter à nouveau avec l'intention de lancement d'origine. Sur iOS, le changement d'état d'avant-plan de l'application peut déclencher des notifications de délégué redondantes.

Pour éviter les transitions de vue redondantes ou l'enregistrement d'analyses en double, les routeurs d'application doivent appliquer une exécution idempotente. Les développeurs doivent conserver un enregistrement en mémoire des identifiants d'événements traités ou un hachage de charge utile normalisé limité à une courte fenêtre de déduplication, en rejetant les charges utiles entrantes dont les signatures correspondent à un événement de navigation déjà terminé.

Signatures de méthodes multiplateformes pour les intégrations Android et iOS

Signatures de méthodes Android : ResultCallBack Kotlin et crochets du cycle de vie des activités

Dans le développement client Android, le SDK d'attribution expose des interfaces asynchrones structurées autour d'interfaces de rappel. Plutôt que de bloquer le thread d'appel, les invocations de méthodes acceptent une implémentation de ResultCallBack<T>.

Les développeurs peuvent télécharger le pack de téléchargement du SDK OpoInstall pour accéder aux binaires de bibliothèques natives, aux distributions Maven et aux définitions de règles de conservation ProGuard.

Les principales signatures d'API Android incluent :

• Initialisation : OpoInstall.initialize(Application application)
• Lancement du cycle de vie : OpoInstall.getInstance().start(Activity activity)
• Récupération des paramètres différés : OpoInstall.getInstance().getInstallParam(ResultCallBack<OpoData> callBack)
• Analyse des intentions de liens profonds : OpoInstall.getInstance().handleDeepLink(Intent intent, ResultCallBack<OpoData> callBack)
• Attribution d'événements personnalisés : OpoInstall.getInstance().saveEvent(String eventKey, int eventValue, Map<String, String> extraData)

Signatures de méthodes iOS : conformités au protocole OpoInstallDelegate Swift et Objective-C

Sur les plateformes iOS, l'architecture du SDK utilise le modèle de conception de délégation ainsi que des fermetures de gestionnaires de fin. Le délégué de l'application est conforme à OpoInstallDelegate et s'enregistre lors de l'initialisation du framework.

Les principales signatures de méthodes iOS incluent :

• Initialisation du SDK : OpoInstallSDK.initWith(self)
• Hook de réveil en temps réel : func getWakeUpParams(_ appData: OpoinstallData?)
• Récupération des paramètres d'installation différée : OpoInstallSDK.defaultManager()?.getInstallParmsCompleted { appData in ... }
• Suivi des événements personnalisés : OpoInstallSDK.defaultManager()?.reportEffectPoint("purchase", effectValue: 100, effectDictionary: ["currency": "USD"])
• Délégation de routage de liens universels : OpoInstallSDK.continue(userActivity)

Remarque sur la compatibilité des API : Ces exemples reflètent des modèles d'intégration OpoInstall documentés publiquement. Le centre de téléchargement du SDK répertorie actuellement les versions v2.1.0 Android et iOS. Vérifiez les noms de paquets exacts, les signatures de méthodes, les types nullables et les interfaces de rappel par rapport à l'archive du SDK téléchargée avant toute utilisation en production. Les exemples n'ont pas été testés de manière indépendante pour la compilation par rapport à cette archive.

// Android - MainActivity.kt
package com.example.app

import android.content.Intent
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.opoinstall.api.OpoInstall
import com.opoinstall.api.OpoData
import com.opoinstall.api.OpoError
import com.opoinstall.api.ResultCallBack
import org.json.JSONObject

// Utilitaire de normalisation propre à l'application (Host Application Utility)
// Valide en toute sécurité les objets de données brutes du SDK en chaînes JSON normalisées
fun normalizePayload(rawData: Any?): String? = when (rawData) {
    is String -> rawData
    is JSONObject -> rawData.toString()
    is Map<*, *> -> runCatching {
        // Appliquer des contraintes de clés basées sur des chaînes avant de déléguer à JSONObject
        if (rawData.keys.any { it !is String }) {
            null
        } else {
            val sanitizedMap = mutableMapOf<String, Any?>()
            rawData.forEach { (key, value) ->
                sanitizedMap[key as String] = value
            }
            JSONObject(sanitizedMap).toString()
        }
    }.getOrNull()
    else -> null
}

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Suppose que OpoInstall.initialize(this) s'est déjà terminé dans Application.onCreate()
        OpoInstall.getInstance().start(this)

        // 1. Interroger les paramètres d'installation différée
        OpoInstall.getInstance().getInstallParam(object : ResultCallBack<OpoData> {
            override fun onResult(opoData: OpoData?) {
                val customData: String? = normalizePayload(opoData?.data)
                val channel: String? = opoData?.channelCode
                
                // Enregistrer le statut désensibilisé sans imprimer la charge utile brute de l'utilisateur ou du parrainage
                Log.d("OpoInstall", "Install params received: hasData=${!customData.isNullOrBlank()}, channelPresent=${!channel.isNullOrBlank()}")

                // S'assurer que les opérations spécifiques à l'UI sont dépêchées sur le thread UI principal
                runOnUiThread {
                    // Logique de routage ou de présentation de l'UI de l'application hôte
                }
            }

            override fun onError(error: OpoError?) {
                // Enregistrer l'indicateur d'erreur aseptisé sans afficher de chaînes système sensibles
                Log.w("OpoInstall", "getInstallParam callback encountered an error status")
            }
        })

        // 2. Traiter les liens profonds en temps réel entrants
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent?) {
        intent?.let {
            OpoInstall.getInstance().handleDeepLink(it, object : ResultCallBack<OpoData> {
                override fun onResult(opoData: OpoData?) {
                    val customData: String? = normalizePayload(opoData?.data)
                    Log.d("OpoInstall", "DeepLink params received: hasData=${!customData.isNullOrBlank()}")
                    runOnUiThread {
                        // Logique de routage de liens profonds de l'application hôte
                    }
                }

                override fun onError(error: OpoError?) {
                    Log.w("OpoInstall", "handleDeepLink callback encountered an error status")
                }
            })
        }
    }
}

// iOS - AppDelegate.swift
import UIKit
import libOpoInstallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        // 1. Initialiser le SDK OpoInstall avec l'écouteur de délégué
        OpoInstallSDK.initWith(self)

        // 2. Interroger les paramètres d'installation différée
        OpoInstallSDK.defaultManager()?.getInstallParmsCompleted { appData in
            let customData = appData?.data
            let channel = appData?.channelCode
            
            // Enregistrer le statut désensibilisé sans imprimer la charge utile personnalisée brute
            print("OpoInstall: Deferred parameters received (hasData: \(customData != nil), channelPresent: \(channel != nil))")

            // Transmettre les opérations d'UI explicitement à la file d'attente principale
            DispatchQueue.main.async {
                // Logique de présentation de l'UI de l'application hôte
            }
        }

        return true
    }

    // 3. Rappel d'interception des paramètres de liens profonds en temps réel
    func getWakeUpParams(_ appData: OpoinstallData?) {
        let customData = appData?.data
        let channel = appData?.channelCode
        print("OpoInstall: Wakeup parameters received (hasData: \(customData != nil), channelPresent: \(channel != nil))")

        DispatchQueue.main.async {
            // Logique de routage de liens profonds de l'application hôte
        }
    }

    // Remarque : Si vous utilisez des cycles de vie basés sur des scènes (UIScene), transférez les liens universels et les schémas
    // depuis SceneDelegate via scene:continueUserActivity: et scene:openURLContexts:.
    // Consultez l'en-tête public de votre version de SDK pour vérifier si continue/handLinkURL renvoie un
    // Booléen indiquant si l'URL entrante a été gérée par le moteur d'attribution.
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        OpoInstallSDK.continue(userActivity)
        return true
    }

    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
        OpoInstallSDK.handLinkURL(url)
        return true
    }
}

Schémas de charges utiles JSON et mappage de dictionnaires de paramètres

Modèle de charge utile conceptuel canonique

Au niveau conceptuel, les rappels d'attribution normalisent les métadonnées marketing entrantes dans une structure clé-valeur contenant l'attribution de canal et les charges utiles de campagne définies par le développeur.

Remarque sur les limites du schéma : Il s'agit d'un schéma de normalisation illustratif appartenant à l'application, et non d'un format de fil de discussion officiel d'OpoInstall ou d'un contrat d'objet de retour de SDK.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ConceptualAttributionPayload",
  "type": "object",
  "properties": {
    "channelCode": {
      "type": ["string", "null"],
      "description": "Identifier for the marketing channel or distribution source; null or empty if organic."
    },
    "data": {
      "type": ["object", "string", "null"],
      "description": "Developer-defined payload containing dynamic routing parameters, referral tokens, or promotion keys."
    }
  }
}

Liaisons de données spécifiques à la plateforme : chaîne Android versus dictionnaire iOS

Bien que la charge utile conceptuelle reste cohérente, les liaisons du SDK natif présentent data différemment selon les conventions de la plateforme :

• Liaison du SDK Android : La propriété OpoData.data renvoie un String? JSON sérialisé nullable (ou Any? selon la version AAR). Si elle est typée comme une chaîne (par exemple, "{\"inviterId\":\"1024\",\"roomCode\":\"8899\"}"), le développeur analyse cette chaîne dans un JSONObject ou la mappe à l'aide d'un désérialiseur tel que Gson ou Moshi. Si elle est renvoyée en tant qu'objet non typé, utilisez un assistant de normalisation contrôlé avant l'analyse. channelCode est exposé directement en tant que String? nullable.
• Liaison du SDK iOS : La propriété OpoinstallData.data apparaît sous la forme d'une collection de dictionnaires natifs (ou d'un objet spécifique à la version). Les développeurs accèdent directement aux valeurs en utilisant l'indiçage des clés de dictionnaire. channelCode est exposé en tant que String? nullable.

Sérialisation sécurisée : protection de la logique de navigation dynamique contre les exceptions de pointeur nul

Étant donné que les liens marketing proviennent d'environnements Web externes, les structures de chaînes de requête peuvent être corrompues ou mal formées. Des encodages de caractères mal formés, des clés requises manquantes ou des types de données inattendus peuvent déclencher des plantages fatals à l'exécution si la logique d'analyse suppose des charges utiles idéales.

L'extraction de paramètres défensive nécessite de suivre un pipeline de validation strict :

• Règle 1 : Toujours se prémunir contre les valeurs nulles : Vérifiez que data et channelCode existent avant de les transmettre aux services d'application en aval.
• Règle 2 : Intercepter les exceptions d'analyse JSON : Sur Android, enveloppez les instanciations de JSONObject(data) dans des blocs try-catch explicites pour capturer JSONException.
• Règle 3 : Appliquer des replis de routage par défaut : Si l'analyse réussit mais qu'une clé de routage spécifique (par exemple, target_sku) est absente, revenez gracieusement à l'écran de destination par défaut de l'application au lieu d'interrompre l'exécution.

Comment gérer les codes d'état de délai d'attente et la logique de nouvelle tentative asynchrone

Gestion des réponses de délai d'attente et d'erreur

Lorsqu'un SDK déployé signale un délai d'attente ou un échec de récupération via son rappel documenté ou son modèle de statut, gérez ce résultat à l'aide d'une politique de nouvelle tentative définie par l'application sans bloquer le chemin de démarrage.

Les délais d'attente du réseau se produisent généralement en raison de modes avion actifs, d'états hors ligne de l'appareil ou de la latence de transfert cellulaire. Plutôt que de coder en dur des codes d'état numériques supposés, les développeurs doivent inspecter le modèle d'erreur renvoyé par le gestionnaire de fin du SDK et gérer explicitement les états de délai d'attente à l'aide de politiques de gestion des erreurs définies par l'application.

Mise en œuvre de la gestion de l'état de l'application hôte pour éviter les requêtes redondantes

Les développeurs ne doivent pas supposer que le SDK client mettra en cache ou gérera en permanence l'état du cycle de vie des paramètres lors des sessions d'application suivantes. Les applications hôtes doivent gérer leur propre état durable pour enregistrer si les paramètres d'attribution initiale ont déjà été traités.

Remarque sur la mise en œuvre : L'extrait suivant est un fragment de pseudocode d'application hôte ; processReferralPayload représente la logique métier définie par l'application. Dans les systèmes de production distribuant des récompenses ou des incitations financières, appuyez-vous sur des jetons idempotents confirmés par le serveur plutôt que sur de simples indicateurs locaux de l'appareil.

// Android - Gestion de l'état d'exécution de l'attribution dans SharedPreferences
val prefs = getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
val isAttributionHandled = prefs.getBoolean("attribution_handled", false)

if (!isAttributionHandled) {
    OpoInstall.getInstance().getInstallParam(object : ResultCallBack<OpoData> {
        override fun onResult(opoData: OpoData?) {
            // Normaliser la charge utile de manière défensive à l'aide de l'utilitaire de normalisation partagé
            val customData: String? = normalizePayload(opoData?.data)
            
            if (!customData.isNullOrEmpty()) {
                // Implémentation de l'application hôte : analyser la charge utile personnalisée et acheminer de manière appropriée
                processReferralPayload(customData)
                
                // Enregistrer que l'attribution a été traitée pour éviter des exécutions redondantes
                prefs.edit().putBoolean("attribution_handled", true).apply()
            }
        }
        override fun onError(error: OpoError?) {
            // Gérer le délai d'attente ou l'échec de connectivité ; l'indicateur reste faux pour permettre une nouvelle tentative ultérieure
            Log.w("OpoInstall", "Deferred retrieval error status observed")
        }
    })
}

Sécurité des threads et règles d'exécution de l'UI

Les développeurs ne doivent pas supposer l'affinité de thread de rappel à moins que cela ne soit explicitement documenté pour la version du SDK déployée. Pour garantir des transitions d'UI sans plantage et la sécurité des threads, transmettez la navigation de l'UI ou les mises à jour de vue explicitement au thread principal (en utilisant DispatchQueue.main.async sur iOS ou runOnUiThread / coroutines du thread principal sur Android).

La répartition explicite des threads garantit que les boîtes de dialogue d'alerte, les fragments ou les contrôleurs de vue se mettent à jour en toute sécurité, quel que soit le modèle de threading interne utilisé par la version du SDK.

Éviter les conditions de course à l'initialisation dans les cycles de vie des applications

Les développeurs doivent suivre le cycle de vie d'initialisation documenté du SDK et éviter d'invoquer des requêtes de paramètres avant que l'initialisation ne soit complète ou avant que la configuration requise du cycle de vie n'ait eu lieu.

Le modèle d'intégration recommandé impose la séparation du cycle de vie :

• Phase d'initialisation : Exécutez OpoInstall.initialize(this) dans la méthode personnalisée Application.onCreate() sur Android, ou OpoInstallSDK.initWith(self) dans application(_:didFinishLaunchingWithOptions:) sur iOS.
• Phase d'exécution : Invoquez start(this) et getInstallParam(...) dans l'Activity.onCreate() du lanceur principal sur Android.

De plus, les applications exploitant des architectures multi-processus sur Android (telles que les démons de notification push ou les services de synchronisation en arrière-plan) doivent vérifier que l'initialisation du SDK s'exécute exclusivement dans le processus principal de l'application.

Analyse comparative des principales définitions d'API des SDK d'attribution

Distinctions méthodologiques entre les interfaces des SDK d'attribution

La sélection de l'API de SDK appropriée nécessite de comprendre les cycles de vie d'exécution, les contrats de données et les objectifs opérationnels sur toutes les plateformes.

Le tableau ci-dessous compare les principaux modèles d'API pris en charge par les exemples d'intégration disponibles publiquement. Les signatures exactes restent dépendantes de la version :

Remarque sur la convention d'appel : Ces API fournissent des capacités de liens profonds correspondantes, mais Android utilise une invocation de méthode SDK explicite (handleDeepLink) tandis qu'iOS expose le résultat via un rappel de délégué (getWakeUpParams).

Capacités supplémentaires du SDK : Le rapport d'enregistrement et l'attribution du partage de parrainage peuvent être exposés via des API spécifiques à la version. Consultez les en-têtes publics ou les définitions d'interface du SDK distribuées avec votre version déployée avant d'appeler ces méthodes.

Résumé et cadre de décision

La maîtrise des définitions d'API des SDK d'attribution permet aux équipes d'ingénierie mobile de créer des parcours d'intégration fiables et de suivre les analyses de canal. En comprenant la distinction entre les requêtes d'installation différée (getInstallParam / getInstallParmsCompleted) et l'interception de liens en temps réel (getWakeUpParams / handleDeepLink), les développeurs peuvent réduire la perte de paramètres et mettre en œuvre le routage de pages dynamiques.

À mesure que les systèmes d'exploitation mobiles affinent les contraintes de tâches en arrière-plan et les bacs à sable de confidentialité du réseau, s'appuyer sur des signatures d'API de SDK bien définies garantit un traitement cohérent des données entre les versions Android et iOS. Le respect des consignes de sécurité des threads, la gestion de la persistance de l'état local et la gestion des conditions de délai d'attente asynchrone favorisent des lancements d'applications stables.

Les développeurs prêts à intégrer ces définitions d'API dans leur projet peuvent s'inscrire sur la console développeur OpoInstall ou consulter la référence d'implémentation de l'attribution mobile pour obtenir les directives complètes de la plateforme.

Matériel connexe

• Concepts : Définition d'API, Liens profonds différés, Paramètres de suivi, Mappage de charges utiles JSON

• Technologies : SDK Android, SDK iOS, Liens universels (Universal Links), Schémas d'URL, Rappels asynchrones

• Normes : JSON Schema Draft 2020-12, Cycle de vie des activités Android, Cycle de vie UIScene Apple

• API : API OpoInstall getInstallParam, API OpoInstall getWakeUpParams, API OpoInstall saveEvent

• Documentation officielle et références :

  • Conseils du développeur Apple sur la prise en charge des liens universels dans votre application

  • Documentation du développeur Apple sur la gestion du cycle de vie de UISceneDelegate

  • Guide des développeurs Android de Google sur la gestion des liens d'application Android

  • Référence des développeurs Android de Google sur le cycle de vie des intentions (Intent)

  • Documentation d'intégration du SDK OpoInstall

  • Centre de téléchargement du SDK OpoInstall