Ajouter un emplacement (héritage)

Pour les partenaires Rokt, le SDK Android peut être utilisé pour afficher des emplacements en superposition ou intégrés dans votre application Android.

Avant de commencer

Assurez-vous que le SDK Android de Rokt a déjà été intégré dans votre application.

Emplacements en superposition

Exécutez le SDK dans votre activité/fragment souhaité, en ajoutant les attributs client appropriés et le mappage d'emplacement. Le code d'exemple utilise la méthode onCreate pour lancer l'emplacement.

La vue du widget Rokt s'affiche après un court délai, configurable via la plateforme Rokt. Le SDK fournit des événements de rappel optionnels pour lorsque la vue se charge et se décharge.

Vous pouvez dicter quels attributs client sont inclus dans votre intégration Rokt. Plus d'informations sur les champs de données disponibles peuvent être trouvées sur la page des attributs. Si vous souhaitez intégrer plus d'attributs, vous pouvez ajouter des lignes de code supplémentaires pour chaque nouvel attribut aux exemples ci-dessous.

Java
Kotlin

import com.rokt.roktsdk.Rokt

class ConfirmationActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        // Inclure les attributs consommateurs appropriés
        val attributes = hashMapOf(
                Pair("email", "j.smith@example.com"),
                Pair("firstname", "Jenny"),
                Pair("lastname", "Smith"),
                Pair("mobile", "(323) 867-5309"),
                Pair("postcode", "90210"),
                Pair("country", "US"))

        Rokt.execute("RoktExperience",
            attributes,
            object : Rokt.RoktCallback {
                override fun onUnload(reason: Rokt.UnloadReasons) {
                }
                override fun onLoad() {
                }
                override fun onShouldHideLoadingIndicator() {
                }
                override fun onShouldShowLoadingIndicator() {
                }
            }
        )
        ...
    }

import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String,String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        Rokt.INSTANCE.execute("RoktExperience",
            attributes,
            new Rokt.RoktCallback() {
                @Override
                public void onLoad() {
                }
                @Override
                public void onUnload(Rokt.UnloadReasons unloadReasons) {
                }
                @Override
                public void onShouldHideLoadingIndicator() {
                }
                @Override
                public void onShouldShowLoadingIndicator() {
                }
            }
        )
        ...
    }
}

Fonctions optionnelles

Fonction	But
`Rokt.close()`	Utilisé pour fermer automatiquement les emplacements en superposition.

Emplacements intégrés

###Mise à jour de votre fichier XML de mise en page {#updating-your-layout-xml-file}

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.rokt.roktsdk.Widget
        android:id="@+id/roktWidget"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

remarque

Le placement intégré de Rokt peut également être créé dans votre code et inclus dans la mise en page de manière dynamique.

###Exécution du SDK {#executing-the-sdk}

Exécutez le SDK dans l'activité/fragment souhaité, en ajoutant les attributs client appropriés et le mappage de placement. Le code d'exemple utilise la méthode onCreate pour lancer le placement.

Le placement Rokt s'affiche après un court délai, configurable via la plateforme Rokt.

Nous conseillons de définir la hauteur du placement à wrap_content afin que le placement puisse ajuster sa hauteur dynamiquement.

Le SDK fournit des événements de rappel optionnels pour lorsque la vue se charge et se décharge.

Vous pouvez choisir quels attributs client inclure dans votre intégration Rokt. Plus d'informations sur les champs de données disponibles se trouvent sur la page attributs. Si vous souhaitez ajouter plus d'attributs, vous pouvez ajouter des lignes de code supplémentaires pour chaque nouvel attribut aux exemples ci-dessous.

Java
Kotlin

import com.rokt.roktsdk.Widget
import com.rokt.roktsdk.Rokt

class ConfirmationActivity : Activity() {

    private val roktCalllback = object : Rokt.RoktCallback {
        override fun onLoad() {
        }

        override fun onShouldShowLoadingIndicator() {
        }

        override fun onShouldHideLoadingIndicator() {
        }

        override fun onUnload(reason: Rokt.UnloadReasons) {
        }
    }

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

        // Inclure tous les attributs consommateurs appropriés
        val attributes = hashMapOf(
            Pair("email", "j.smith@example.com"),
            Pair("firstname", "Jenny"),
            Pair("lastname", "Smith"),
            Pair("mobile", "(323) 867-5309"),
            Pair("postcode", "90210"),
            Pair("country", "US")
        )

        // Mappage de l'espace réservé du widget avec la configuration de l'emplacement
        val widget = findViewById<Widget>(R.id.roktWidget)
        val placeHolders = hashMapOf(
            Pair("RoktEmbedded1", WeakReference(widget))
        )

        Rokt.execute(
            viewName = "RoktExperience",
            attributes = attributes,
            callback = roktCalllback,
            placeholders = placeHolders
        )
        ...
    }
}

import com.rokt.roktsdk.Widget;
import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {

    private Rokt.RoktCallback roktCallback = new Rokt.RoktCallback() {
        @Override
        public void onLoad() {
        }

        @Override
        public void onShouldShowLoadingIndicator() {
        }

        @Override
        public void onShouldHideLoadingIndicator() {
        }

        @Override
        public void onUnload(@NotNull Rokt.UnloadReasons unloadReasons) {
        }
    };

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String, String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        // Mappage de l'espace réservé du widget avec la configuration de l'emplacement
        Widget widget = findViewById(R.id.roktWidget);
        Map<String, WeakReference<Widget>> placeHolders = new HashMap<>();
        placeHolders.put("RoktEmbedded1", new WeakReference<>(widget));

        Rokt.INSTANCE.execute("RoktExperience",
                attributes,
                roktCallback,
                placeHolders);
        ...
    }
}

remarque

Si vous souhaitez mettre à jour le nom de la vue RoktExperience ou le nom de l'espace réservé RoktEmbedded1 avec une valeur différente, contactez votre gestionnaire de compte Rokt pour vous assurer que les placements Rokt sont configurés de manière cohérente.

Composant Jetpack Compose

À partir de la version majeure 4 du SDK Android de Rokt, vous pouvez ajouter une mise en page Rokt en utilisant le composable RoktLayout. Cela supprime la nécessité d'appeler Rokt.execute et prend en charge une intégration déclarative plus moderne en utilisant Compose.

###Ajout du composant {#adding-the-component}

import com.rokt.roktsdk.RoktLayout

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        RoktLayout(
            sdkTriggered = true,
            viewName = "RoktExperience",
            attributes = hashMapOf(
                Pair("email", "j.smith@example.com"),
                Pair("firstname", "Jenny"),
                Pair("lastname", "Smith"),
                Pair("mobile", "(323) 867-5309"),
                Pair("postcode", "90210"),
                Pair("country", "US")
            ),
            location = "RoktEmbedded1", // Si vous utilisez une mise en page intégrée
            onLoad = {},
            onUnload = {},
            onShouldShowLoadingIndicator = {},
            onShouldHideLoadingIndicator = {},
        )
    }
}

remarque

Vous pouvez utiliser le composant RoktLayout pour les mises en page intégrées et superposées.

Événements

Le SDK fournit les événements sur chaque page sous forme de flux via l'API Rokt.events. Les utilisateurs du SDK peuvent tirer parti du mécanisme Kotlin Flow pour consommer les événements produits par le SDK.

// owner: LifecycleOwner
owner.lifecycleScope.launch {
    owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
        Rokt.events("viewName").collect { roktEvent ->
            Log.d("RoktEvent", "Événement reçu $roktEvent")
        }
    }
}

Objets d'événement

Événement	Description	Paramètres
ShowLoadingIndicator	Déclenché avant que le SDK n'appelle le backend Rokt
HideLoadingIndicator	Déclenché lorsque le SDK reçoit un succès ou un échec du backend Rokt
OfferEngagement	Déclenché lorsque l'utilisateur interagit avec l'offre	placementId: String
PositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre	placementId: String
FirstPositiveEngagement	Déclenché lorsque l'utilisateur interagit positivement avec l'offre pour la première fois	placementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractive	Déclenché lorsqu'un emplacement a été rendu et est interactif	placementId: String
PlacementReady	Déclenché lorsqu'un emplacement est prêt à être affiché mais n'a pas encore rendu de contenu	placementId: String
PlacementClosed	Déclenché lorsqu'un emplacement est fermé par l'utilisateur	placementId: String
PlacementCompleted	Déclenché lorsque la progression de l'offre atteint la fin et qu'aucune autre offre n'est disponible à afficher. Également déclenché lorsque le cache est atteint mais que l'emplacement récupéré ne sera pas affiché car il a été précédemment rejeté	placementId: String
PlacementFailure	Déclenché lorsqu'un emplacement n'a pas pu être affiché en raison d'un échec ou lorsqu'aucun emplacement n'est disponible à afficher	placementId: String (optionnel)
OpenUrl	Déclenché lorsque l'utilisateur appuie sur une URL qui est configurée pour être envoyée à l'application partenaire	placementId: String, url: String

Rappels

Le SDK Android de Rokt prend en charge les rappels suivants qui sont passés dans execute en tant qu'objet Rokt.RoktCallback:

onLoad

Le rappel onLoad sera appelé lorsque l'emplacement devient chargé et interactif. Ce rappel ne fournit aucun argument et ne retourne aucune valeur.

onShouldShowLoadingIndicator

Le rappel onShouldShowLoadingIndicator sera appelé lors d'un appel d'exécution réussi, juste avant que le SDK ne déclenche un appel au backend Rokt. Il peut être utilisé pour afficher des vues de progression des indicateurs de chargement en attendant que l'emplacement se charge. Il ne nécessite aucun argument et ne retourne aucune valeur.

remarque

Le comportement de ce rappel a changé entre la version majeure 3 et la version majeure 4 du SDK Android de Rokt. Il n'y a plus de délai d'une seconde avant que le rappel ne soit exécuté. Si vous utilisez ces rappels dans la version majeure 3 et que vous passez à la version majeure 4, testez le comportement pour vous assurer que l'expérience utilisateur n'est pas impactée. Vous pouvez créer un comportement de délai qui convient aux besoins de votre application si nécessaire.

onShouldHideLoadingIndicator

Le rappel onShouldHideLoadingIndicator sera appelé lorsque le SDK obtient une réponse de succès ou d'échec du backend Rokt. Il peut être utilisé pour annuler les vues de progression ou les indicateurs de chargement. Il ne nécessite aucun argument et ne retourne aucune valeur.

###onUnload

Le callback onUnload sera appelé lorsque le SDK ferme le placement. Il sera également déclenché si l'appel d'exécution échoue. Il reçoit un Rokt.UnloadReasons comme argument, mais ne retourne aucune valeur. Les raisons de déchargement sont les suivantes :

Valeur	Raison
NO_OFFERS	Il n'y a pas d'offres éligibles à afficher
FINISHED	Un placement ou une mise en page rendu a été fermé
TIMEOUT	Délai d'attente lors de la demande de réponse du backend
NETWORK_ERROR	Une erreur réseau s'est produite
NO_WIDGET	Le placement ou la mise en page retourné est invalide ou vide
INIT_FAILED	La demande d'initialisation a échoué avant l'appel d'exécution
UNKNOWN_PLACEHOLDER	Inadéquation de la chaîne de caractères de l'espace réservé (disponible à partir de la version 4.x.x)
UNKNOWN	Raison générique

Avant de commencer​

Emplacements en superposition​

Fonctions optionnelles​

Emplacements intégrés​

Composant Jetpack Compose​

Événements​

Objets d'événement​

Rappels​

onLoad​

onShouldShowLoadingIndicator​

onShouldHideLoadingIndicator​

Avant de commencer

Emplacements en superposition

Fonctions optionnelles

Emplacements intégrés

Composant Jetpack Compose

Événements

Objets d'événement

Rappels

onLoad

onShouldShowLoadingIndicator

onShouldHideLoadingIndicator