feat: Add PlacementOptions support to Rokt integration

.trunk/trunk.yaml

@@ -29,7 +29,7 @@ lint:
     - actionlint@1.7.7
     - checkov@3.2.470
     - git-diff-check
-    - ktlint@0.48.2
+    - ktlint@1.7.1
     - markdownlint@0.45.0
     - prettier@3.6.2
     - shellcheck@0.11.0

android-core/src/main/java/com/mparticle/internal/KitFrameworkWrapper.java

@@ -19,15 +19,11 @@
 import com.mparticle.MPEvent;
 import com.mparticle.MParticle;
 import com.mparticle.MParticleOptions;
-import com.mparticle.MpRoktEventCallback;
-import com.mparticle.RoktEvent;
 import com.mparticle.WrapperSdkVersion;
 import com.mparticle.consent.ConsentState;
 import com.mparticle.identity.IdentityApiRequest;
 import com.mparticle.identity.MParticleUser;
 import com.mparticle.internal.listeners.InternalListenerManager;
-import com.mparticle.rokt.RoktConfig;
-import com.mparticle.rokt.RoktEmbeddedView;
 import com.mparticle.rokt.RoktOptions;
 
 import org.json.JSONArray;
@@ -43,8 +39,6 @@
 import java.util.TreeMap;
 import java.util.concurrent.ConcurrentLinkedQueue;
 
-import kotlinx.coroutines.flow.Flow;
-
 public class KitFrameworkWrapper implements KitManager {
     private final Context mContext;
     final CoreCallbacks mCoreCallbacks;
@@ -669,29 +663,12 @@ public void reset() {
     }
 
     @Override
-    public void execute(@NonNull String viewName,
-                        @NonNull Map<String, String> attributes,
-                        @Nullable MpRoktEventCallback mpRoktEventCallback,
-                        @Nullable Map<String, WeakReference<RoktEmbeddedView>> placeHolders,
-                        @Nullable Map<String, WeakReference<Typeface>> fontTypefaces,
-                        @Nullable RoktConfig config) {
-        if (mKitManager != null) {
-            mKitManager.execute(viewName,
-                    attributes,
-                    mpRoktEventCallback,
-                    placeHolders,
-                    fontTypefaces,
-                    config);
-        }
-    }
-
-    @Override
-    public Flow<RoktEvent> events(@NonNull String identifier) {
+    @Nullable
+    public RoktKitApi getRoktKitApi() {
         if (mKitManager != null) {
-            return mKitManager.events(identifier);
-        } else {
-            return flowOf();
+            return mKitManager.getRoktKitApi();
         }
+        return null;
     }
 
     @Override
@@ -701,43 +678,6 @@ public void setWrapperSdkVersion(@NonNull WrapperSdkVersion wrapperSdkVersion) {
         }
     }
 
-    @Override
-    public void purchaseFinalized(@NonNull String placementId, @NonNull String catalogItemId, boolean status) {
-        if (mKitManager != null) {
-            mKitManager.purchaseFinalized(placementId, catalogItemId, status);
-        }
-    }
-
-    @Override
-    public void close() {
-        if (mKitManager != null) {
-            mKitManager.close();
-        }
-    }
-
-    @Override
-    public void prepareAttributesAsync(@NonNull Map<String, String> attributes) {
-        if (mKitManager != null) {
-            mKitManager.prepareAttributesAsync(attributes);
-        }
-    }
-
-    @Override
-    public void setSessionId(@NonNull String sessionId) {
-        if (mKitManager != null) {
-            mKitManager.setSessionId(sessionId);
-        }
-    }
-
-    @Override
-    @Nullable
-    public String getSessionId() {
-        if (mKitManager != null) {
-            return mKitManager.getSessionId();
-        }
-        return null;
-    }
-
     static class CoreCallbacksImpl implements CoreCallbacks {
         KitFrameworkWrapper mKitFrameworkWrapper;
         ConfigManager mConfigManager;
@@ -852,4 +792,4 @@ public void onKitApiCalled(String methodName, int kitId, Boolean used, Object...
             }
         };
     }
-}
+}

android-core/src/main/java/com/mparticle/internal/KitManager.java

@@ -16,14 +16,10 @@
 import com.mparticle.MPEvent;
 import com.mparticle.MParticle;
 import com.mparticle.MParticleOptions;
-import com.mparticle.MpRoktEventCallback;
-import com.mparticle.RoktEvent;
 import com.mparticle.WrapperSdkVersion;
 import com.mparticle.consent.ConsentState;
 import com.mparticle.identity.IdentityApiRequest;
 import com.mparticle.identity.MParticleUser;
-import com.mparticle.rokt.RoktConfig;
-import com.mparticle.rokt.RoktEmbeddedView;
 import com.mparticle.rokt.RoktOptions;
 
 import org.json.JSONArray;
@@ -33,8 +29,6 @@
 import java.util.Map;
 import java.util.Set;
 
-import kotlinx.coroutines.flow.Flow;
-
 public interface KitManager {
 
     WeakReference<Activity> getCurrentActivity();
@@ -133,41 +127,19 @@ public interface KitManager {
 
     void reset();
 
-    void execute(@NonNull String identifier,
-                 @NonNull Map<String, String> attributes,
-                 @Nullable MpRoktEventCallback mpRoktEventCallback,
-                 @Nullable Map<String, WeakReference<RoktEmbeddedView>> embeddedViews,
-                 @Nullable Map<String, WeakReference<Typeface>> fontTypefaces,
-                 @Nullable RoktConfig config);
-
-    Flow<RoktEvent> events(@NonNull String identifier);
-
-    void setWrapperSdkVersion(@NonNull WrapperSdkVersion wrapperSdkVersion);
-
-    void purchaseFinalized(@NonNull String placementId, @NonNull String catalogItemId, boolean status);
-
-    void close();
-
-    /**
-     * Set the session id to use for the next execute call.
-     *
-     * @param sessionId The session id to be set. Must be a non-empty string.
-     */
-    void setSessionId(@NonNull String sessionId);
-
     /**
-     * Get the session id to use within a non-native integration e.g. WebView.
+     * Get the RoktKitApi implementation if available.
      *
-     * @return The session id or null if no session is present.
+     * @return RoktKitApi instance or null if Rokt Kit is not configured or active
      */
     @Nullable
-    String getSessionId();
+    RoktKitApi getRoktKitApi();
 
-    void prepareAttributesAsync(@NonNull Map<String, String> attributes);
+    void setWrapperSdkVersion(@NonNull WrapperSdkVersion wrapperSdkVersion);
 
     enum KitStatus {
         NOT_CONFIGURED,
         STOPPED,
         ACTIVE
     }
-}
+}

android-core/src/main/kotlin/com/mparticle/Rokt.kt

@@ -3,7 +3,9 @@ package com.mparticle
 import android.graphics.Typeface
 import com.mparticle.internal.ConfigManager
 import com.mparticle.internal.KitManager
+import com.mparticle.internal.Logger
 import com.mparticle.internal.listeners.ApiClass
+import com.mparticle.rokt.PlacementOptions
 import com.mparticle.rokt.RoktConfig
 import com.mparticle.rokt.RoktEmbeddedView
 import kotlinx.coroutines.flow.Flow
@@ -12,6 +14,17 @@ import java.lang.ref.WeakReference
 
 @ApiClass
 class Rokt internal constructor(private val mConfigManager: ConfigManager, private val mKitManager: KitManager) {
+
+    /**
+     * Display a Rokt placement with the specified parameters.
+     *
+     * @param identifier The placement identifier
+     * @param attributes User attributes to pass to Rokt
+     * @param callbacks Optional callback for Rokt events
+     * @param embeddedViews Optional map of embedded view placeholders
+     * @param fontTypefaces Optional map of font typefaces
+     * @param config Optional Rokt configuration
+     */
     @JvmOverloads
     fun selectPlacements(
         identifier: String,
@@ -22,25 +35,46 @@ class Rokt internal constructor(private val mConfigManager: ConfigManager, priva
         config: RoktConfig? = null,
     ) {
         if (mConfigManager.isEnabled) {
-            mKitManager.execute(identifier, HashMap(attributes), callbacks, embeddedViews, fontTypefaces, config)
+            val roktApi = mKitManager.roktKitApi
+            if (roktApi != null) {
+                roktApi.execute(identifier, HashMap(attributes), callbacks, embeddedViews, fontTypefaces, config, buildPlacementOptions())
+            } else {
+                Logger.warning("Rokt Kit is not available. Make sure the Rokt Kit is included in your app.")
+            }
         }
     }
 
+    /**
+     * Get a Flow of Rokt events for the specified identifier.
+     *
+     * @param identifier The placement identifier to listen for events
+     * @return A Flow emitting RoktEvent objects
+     */
     fun events(identifier: String): Flow<RoktEvent> = if (mConfigManager.isEnabled) {
-        mKitManager.events(identifier)
+        mKitManager.roktKitApi?.events(identifier) ?: flowOf()
     } else {
         flowOf()
     }
 
+    /**
+     * Notify Rokt that a purchase has been finalized.
+     *
+     * @param placementId The placement identifier
+     * @param catalogItemId The catalog item identifier
+     * @param status Whether the purchase was successful
+     */
     fun purchaseFinalized(placementId: String, catalogItemId: String, status: Boolean) {
         if (mConfigManager.isEnabled) {
-            mKitManager.purchaseFinalized(placementId, catalogItemId, status)
+            mKitManager.roktKitApi?.purchaseFinalized(placementId, catalogItemId, status)
         }
     }
 
+    /**
+     * Close any active Rokt placements.
+     */
     fun close() {
         if (mConfigManager.isEnabled) {
-            mKitManager.close()
+            mKitManager.roktKitApi?.close()
         }
     }
 
@@ -56,7 +90,7 @@ class Rokt internal constructor(private val mConfigManager: ConfigManager, priva
      */
     fun setSessionId(sessionId: String) {
         if (mConfigManager.isEnabled) {
-            mKitManager.setSessionId(sessionId)
+            mKitManager.roktKitApi?.setSessionId(sessionId)
         }
     }
 
@@ -66,8 +100,23 @@ class Rokt internal constructor(private val mConfigManager: ConfigManager, priva
      * @return The session id or null if no session is present or SDK is not initialized.
      */
     fun getSessionId(): String? = if (mConfigManager.isEnabled) {
-        mKitManager.getSessionId()
+        mKitManager.roktKitApi?.getSessionId()
     } else {
         null
     }
+
+    /**
+     * Prepare attributes asynchronously before executing a placement.
+     *
+     * @param attributes The attributes to prepare
+     */
+    fun prepareAttributesAsync(attributes: Map<String, String>) {
+        if (mConfigManager.isEnabled) {
+            mKitManager.roktKitApi?.prepareAttributesAsync(attributes)
+        }
+    }
+
+    private fun buildPlacementOptions(): PlacementOptions = PlacementOptions(
+        jointSdkSelectPlacements = System.currentTimeMillis(),
+    )
 }

android-core/src/main/kotlin/com/mparticle/internal/RoktKitApi.kt

@@ -0,0 +1,87 @@
+package com.mparticle.internal
+
+import android.graphics.Typeface
+import com.mparticle.MpRoktEventCallback
+import com.mparticle.RoktEvent
+import com.mparticle.rokt.PlacementOptions
+import com.mparticle.rokt.RoktConfig
+import com.mparticle.rokt.RoktEmbeddedView
+import kotlinx.coroutines.flow.Flow
+import java.lang.ref.WeakReference
+
+/**
+ * Interface for Rokt Kit operations.
+ *
+ * Implementations of this interface are provided by the Rokt Kit when it is
+ * configured and active. Use [KitManager.getRoktKitApi] to obtain an instance.
+ */
+interface RoktKitApi {
+    /**
+     * Execute a Rokt placement with the specified parameters.
+     *
+     * @param viewName The identifier for the placement view
+     * @param attributes User attributes to pass to Rokt
+     * @param mpRoktEventCallback Optional callback for Rokt events
+     * @param placeHolders Optional map of embedded view placeholders
+     * @param fontTypefaces Optional map of font typefaces
+     * @param config Optional Rokt configuration
+     * @param options Optional placement options
+     */
+    fun execute(
+        viewName: String,
+        attributes: Map<String, String>,
+        mpRoktEventCallback: MpRoktEventCallback?,
+        placeHolders: Map<String, WeakReference<RoktEmbeddedView>>?,
+        fontTypefaces: Map<String, WeakReference<Typeface>>?,
+        config: RoktConfig?,
+        options: PlacementOptions? = null,
+    )
+
+    /**
+     * Get a Flow of Rokt events for the specified identifier.
+     *
+     * @param identifier The placement identifier to listen for events
+     * @return A Flow emitting RoktEvent objects
+     */
+    fun events(identifier: String): Flow<RoktEvent>
+
+    /**
+     * Notify Rokt that a purchase has been finalized.
+     *
+     * @param placementId The placement identifier
+     * @param catalogItemId The catalog item identifier
+     * @param status Whether the purchase was successful
+     */
+    fun purchaseFinalized(placementId: String, catalogItemId: String, status: Boolean)
+
+    /**
+     * Close any active Rokt placements.
+     */
+    fun close()
+
+    /**
+     * Set the session id to use for the next execute call.
+     *
+     * This is useful for cases where you have a session id from a non-native integration,
+     * e.g. WebView, and you want the session to be consistent across integrations.
+     *
+     * **Note:** Empty strings are ignored and will not update the session.
+     *
+     * @param sessionId The session id to be set. Must be a non-empty string.
+     */
+    fun setSessionId(sessionId: String)
+
+    /**
+     * Get the session id to use within a non-native integration e.g. WebView.
+     *
+     * @return The session id or null if no session is present.
+     */
+    fun getSessionId(): String?
+
+    /**
+     * Prepare attributes asynchronously before executing a placement.
+     *
+     * @param attributes The attributes to prepare
+     */
+    fun prepareAttributesAsync(attributes: Map<String, String>)
+}

android-core/src/main/kotlin/com/mparticle/rokt/PlacementOptions.kt

@@ -0,0 +1,3 @@
+package com.mparticle.rokt
+
+data class PlacementOptions(val jointSdkSelectPlacements: Long, val dynamicPerformanceMarkers: MutableMap<String, Long> = mutableMapOf())