Ajouter un emplacement
Pour les partenaires Rokt, le SDK Android peut être utilisé pour afficher des placements en superposition ou intégrés dans votre application Android.
Avant de commencer
Assurez-vous que le SDK Android Rokt a déjà été intégré dans votre application.
Placements en superposition
Exécutez le SDK dans votre activity/fragment souhaité, en ajoutant tous les attributs client appropriés et le mappage de l'emplacement. L'exemple de code 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 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 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"))
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 | Objectif |
---|---|
Rokt.close() | Utilisé pour fermer automatiquement les placements d'incrustation. |
Placements intégrés
Mise à jour de votre fichier XML de disposition
<?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>
Le placement intégré Rokt peut également être créé dans votre code et inclus dans la disposition de manière dynamique.
Exécution du SDK
Exécutez le SDK dans l'activité/fragment souhaité, en ajoutant tous les attributs clients appropriés et le mappage de placement. L'exemple de code 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 régler la hauteur du placement sur wrap_content
afin que le placement puisse définir sa hauteur de manière dynamique.
Le SDK fournit des événements de rappel optionnels pour le chargement et le déchargement de la vue.
Vous pouvez choisir quels attributs clients inclure dans votre intégration Rokt. Plus d'informations sur les champs de données disponibles peuvent être trouvées 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 roktCallback = 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")
)
// Widget placeholder mappant la vue placeholder 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 ) ... } }
</TabItem>
<TabItem value="Java">
```java
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");
// Widget placeholder mapping the placeholder view with placement location configuration
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);
...
}
}
Si vous souhaitez mettre à jour le nom de la vue RoktExperience
ou le nom du placeholder RoktEmbedded1
avec une valeur différente, contactez votre gestionnaire de compte Rokt pour vous assurer que les emplacements Rokt sont configurés de manière cohérente.
À partir de la version majeure 4 du SDK Rokt pour Android, vous pouvez ajouter une disposition Rokt en utilisant le composant `RoktLayout`. Cela élimine le besoin d'appeler `Rokt.execute` et prend en charge une intégration déclarative plus moderne en utilisant Compose.
### Ajout du composant {#adding-the-component}
```kotlin
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 disposition intégrée
onLoad = {},
onUnload = {},
onShouldShowLoadingIndicator = {},
onShouldHideLoadingIndicator = {},
)
}
}
Vous pouvez utiliser le composant RoktLayout
pour les dispositions intégrées et superposées.
Événements
Le SDK fournit les événements de chaque page sous forme de flux via l'API Rokt.events
. Les utilisateurs du SDK peuvent utiliser le mécanisme de 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", "Event received $roktEvent")
}
}
}
Objets d'événement
Événement | Description | Paramètres |
---|---|---|
ShowLoadingIndicator | Déclenché avant que le SDK appelle le backend de Rokt | |
HideLoadingIndicator | Déclenché lorsque le SDK reçoit un succès ou un échec du backend de 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'il n'y a plus d'offres à afficher. Également déclenché lorsqu'un cache est utilisé mais que l'emplacement récupéré ne sera pas affiché car précédemment rejeté | placementId: String |
PlacementFailure | Déclenché lorsqu'un emplacement ne peut pas être affiché en raison d'une défaillance | placementId: String (optionnel) |
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 le placement sera chargé et interactif. Ce rappel ne fournit aucun argument et ne renvoie aucune valeur.
onShouldShowLoadingIndicator
Le onShouldShowLoadingIndicator
sera appelé après 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 le placement se charge. Il ne nécessite aucun argument et ne renvoie aucune valeur.
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 soit exécuté. Si vous utilisez ces rappels dans la version majeure 3 et que vous effectuez une mise à niveau vers 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 vos applications si nécessaire.
onShouldHideLoadingIndicator
Le callback onShouldHideLoadingIndicator
sera appelé lorsque le SDK obtiendra 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 renvoie 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 renvoie 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 | Expiration lors de la demande de réponse du backend |
NETWORK_ERROR | Une erreur réseau est survenue |
NO_WIDGET | Le placement ou la mise en page retourné est invalide ou vide |
INIT_FAILED | La requête d'initialisation a échoué avant que l'exécution ne soit appelée |
UNKNOWN_PLACEHOLDER | Discordance de la chaîne de caractères du placeholder (disponible à partir de 4.x.x) |
UNKNOWN | Raison générique |