[CHNL-12435] Adding new lifecycle listener function (#241)

* [CHNL-12435] Adding new lifecycle listener function

* Readme recc

Co-authored-by: Evan Masseau <>

* brackets to link init function

---------

Co-authored-by: Evan C Masseau <5167687+evan-masseau@users.noreply.github.com>

Author: dan-peluso

README.md

@@ -84,7 +84,11 @@ persist data. Upon initialize, the SDK registers listeners for your application'
 to gracefully manage background processes.
 
 `Klaviyo.initialize()` **must** be called before any other SDK methods can be invoked. We recommend initializing from 
-the earliest point in your application code, such as the `Application.onCreate()` method.
+the earliest point in your application code, the `Application.onCreate()` method.
+
+**Note:** If you are unable to `Application.onCreate()` (e.g. if your API key is dynamic and not yet available) you
+**must** call `Klaviyo.registerForLifecycleCallbacks(applicationContext)` and provide your API key via `initialize`
+as early as it is available.
 
 ```kotlin
 // Application subclass 
@@ -99,6 +103,9 @@ class YourApplication : Application() {
 
         // Initialize is required before invoking any other Klaviyo SDK functionality 
         Klaviyo.initialize("KLAVIYO_PUBLIC_API_KEY", applicationContext)
+        
+        // If unable to call initialize, you must at least register lifecycle listeners:
+        Klaviyo.registerForLifecycleCallbacks(applicationContext)
     }
 }
 ```

sdk/analytics/src/main/java/com/klaviyo/analytics/Klaviyo.kt

@@ -45,6 +45,23 @@ object Klaviyo {
         if (!Registry.isRegistered<ApiClient>()) Registry.register<ApiClient> { KlaviyoApiClient }
     }
 
+    /**
+     * Use this method to register Klaviyo for lifecycle functions. This is necessary for
+     * apps that are not able to [initialize] Klaviyo immediately on app launch, but would like to
+     * utilize Klaviyo Forms
+     *
+     * @param applicationContext
+     */
+    fun registerForLifecycleCallbacks(applicationContext: Context) = safeApply {
+        val application = applicationContext.applicationContext as? Application
+        application?.apply {
+            unregisterActivityLifecycleCallbacks(Registry.lifecycleCallbacks)
+            unregisterComponentCallbacks(Registry.componentCallbacks)
+            registerActivityLifecycleCallbacks(Registry.lifecycleCallbacks)
+            registerComponentCallbacks(Registry.componentCallbacks)
+        } ?: throw LifecycleException()
+    }
+
     /**
      * Configure Klaviyo SDK with your account's public API Key and application context.
      * This must be called to before using any other SDK functionality
@@ -60,13 +77,7 @@ object Klaviyo {
                 .build()
         )
 
-        val application = applicationContext.applicationContext as? Application
-        application?.apply {
-            unregisterActivityLifecycleCallbacks(Registry.lifecycleCallbacks)
-            unregisterComponentCallbacks(Registry.componentCallbacks)
-            registerActivityLifecycleCallbacks(Registry.lifecycleCallbacks)
-            registerComponentCallbacks(Registry.componentCallbacks)
-        } ?: throw LifecycleException()
+        registerForLifecycleCallbacks(applicationContext)
 
         Registry.get<ApiClient>().startService()
 

sdk/analytics/src/test/java/com/klaviyo/analytics/KlaviyoRegisterForLifecycleCallbacksTest.kt

@@ -0,0 +1,61 @@
+package com.klaviyo.analytics
+
+import android.app.Application
+import com.klaviyo.core.Registry
+import com.klaviyo.core.config.Config
+import com.klaviyo.fixtures.BaseTest
+import io.mockk.every
+import io.mockk.mockk
+import io.mockk.verify
+import io.mockk.verifyAll
+import org.junit.Test
+
+internal class KlaviyoRegisterForLifecycleCallbacksTest : BaseTest() {
+
+    private val mockBuilder = mockk<Config.Builder>().apply {
+        every { apiKey(any()) } returns this
+        every { applicationContext(any()) } returns this
+        every { build() } returns mockConfig
+    }
+
+    private val mockApplicationContext = mockk<Application> {
+        every { applicationContext } returns mockk()
+        every { unregisterActivityLifecycleCallbacks(any()) } returns Unit
+        every { unregisterComponentCallbacks(any()) } returns Unit
+        every { registerActivityLifecycleCallbacks(any()) } returns Unit
+        every { registerComponentCallbacks(any()) } returns Unit
+    }
+
+    private val mockApplication = mockk<Application>().apply {
+        every { applicationContext } returns mockApplicationContext
+    }
+
+    @Test
+    fun `check that lifecycle register function does not touch api key dependent functions`() {
+        val expectedListener = Registry.lifecycleCallbacks
+        val expectedConfigListener = Registry.componentCallbacks
+
+        Klaviyo.registerForLifecycleCallbacks(mockApplication)
+
+        verifyAll {
+            mockApplicationContext.unregisterActivityLifecycleCallbacks(
+                match { it == expectedListener }
+            )
+            mockApplicationContext.registerActivityLifecycleCallbacks(
+                match { it == expectedListener }
+            )
+            mockApplicationContext.unregisterComponentCallbacks(
+                match { it == expectedConfigListener }
+            )
+            mockApplicationContext.registerComponentCallbacks(
+                match { it == expectedConfigListener }
+            )
+        }
+
+        verify(exactly = 0) {
+            mockBuilder.apiKey(any())
+            mockBuilder.applicationContext(any())
+            mockBuilder.build()
+        }
+    }
+}