My Article

("article") pageTracker = permutive.trackPage( title = article.title, url = Uri.parse(article.url), referrer = Uri.parse(intent.getStringExtra("referrer")), eventProperties = EventProperties.from( "article_id" to article.id, "category" to article.category, "author" to article.author, "published_at" to article.publishedDate, "word_count" to article.wordCount ) ) setupScrollTracking() } } ``` ```kotlin theme={"dark"} class ProductActivity : AppCompatActivity() { private lateinit var pageTracker: PageTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val product = viewModel.product.value pageTracker = permutive.trackPage( title = product.name, url = Uri.parse("app://product/${product.id}"), eventProperties = EventProperties.from( "product_id" to product.id, "product_name" to product.name, "category" to product.category, "price" to product.price, "in_stock" to product.inStock ) ) addToCartButton.setOnClickListener { pageTracker.track( "ProductAddedToCart", EventProperties.from( "product_id" to product.id, "quantity" to 1 ) ) } } } ``` For video content itself, use [MediaTracker](/sdks/mobile/android/features/video-tracking). For video details/description pages: ```kotlin theme={"dark"} class VideoDetailsActivity : AppCompatActivity() { private lateinit var pageTracker: PageTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) pageTracker = permutive.trackPage( title = video.title, url = Uri.parse("app://video/${video.id}/details"), eventProperties = EventProperties.from( "video_id" to video.id, "video_title" to video.title, "genre" to video.genre, "duration_seconds" to video.durationSeconds ) ) playButton.setOnClickListener { pageTracker.track("VideoPlayButtonClicked") startVideoPlayer() } } } ``` *** ## When to Use PageTracker vs EventTracker ### Use PageTracker When: * ✅ Tracking article/content views * ✅ Tracking screen views in your app * ✅ Measuring time spent on a page/screen * ✅ Tracking scroll depth * ✅ You want contextual cohorts * ✅ Events are associated with a page context ### Use EventTracker Only When: * ⚠️ Tracking standalone events (button clicks not tied to pages) * ⚠️ Tracking background events * ⚠️ Events have no page context > 💡 Default to PageTracker > > Most customer implementations should primarily use PageTracker. EventTracker is for specific use cases. See [Event Tracking](/sdks/mobile/android/features/event-tracking) for EventTracker documentation. *** ## Troubleshooting **Problem:** Engaged time is always 0. **Cause:** Not calling `pause()` and `resume()`. **Solution:** Implement lifecycle callbacks: ```kotlin theme={"dark"} override fun onPause() { super.onPause() pageTracker.pause() // IMPORTANT } override fun onResume() { super.onResume() pageTracker.resume() // IMPORTANT } ``` **Problem:** App memory usage grows over time. **Cause:** Not closing PageTracker. **Solution:** Always close in `onDestroy()`: ```kotlin theme={"dark"} override fun onDestroy() { super.onDestroy() pageTracker.close() // IMPORTANT } ``` **Problem:** No contextual cohorts for pages. **Causes:** 1. Feature not enabled 2. Not providing URLs 3. URLs not publicly accessible **Solutions:** 1. Contact Customer Success Manager to enable 2. Always provide URLs in `trackPage()` 3. Ensure URLs are publicly accessible for web content See [Contextual Data](/sdks/mobile/android/core-concepts/contextual-data) for details. **Problem:** Pageview events not tracked. **Solutions:** 1. Enable debug logging: `permutive.setDeveloperMode(true)` 2. Check logs for "Published events with names (Pageview)" 3. Verify event properties match your schema 4. See [Verification Guide](/sdks/mobile/android/getting-started/verification) *** ## Best Practices * Create PageTracker in `onCreate()` * Call `pause()` in `onPause()` * Call `resume()` in `onResume()` * Call `close()` in `onDestroy()` * Provide URLs when possible for contextual cohorts * Track scroll depth for content pages * Use PageTracker for all page/screen views * Forget to close PageTracker * Create multiple PageTrackers for the same page * Skip pause/resume calls * Use EventTracker when PageTracker is more appropriate *** ## Related Documentation Get started with the SDK Add structured data to events Content-based segmentation For standalone events For video content Verify your integration *** ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ### PageTracker Interface * `pause()` - Pause engagement tracking * `resume()` - Resume engagement tracking * `updatePercentageViewed(percentage: Float)` - Update scroll depth * `track(eventName: String)` - Track event with this page context * `track(eventName: String, properties: EventProperties?)` - Track event with properties * `close()` - Complete page tracking and send PageviewComplete event # Triggers Provider Source: https://docs.permutive.com/sdks/mobile/android/features/triggers-provider React to real-time cohort membership changes The `TriggersProvider` enables real-time reactive programming patterns by allowing you to observe cohort membership changes and trigger actions when users enter or exit specific cohorts. This is powerful for personalizing user experiences, A/B testing, and dynamic content delivery. ## Overview The Triggers Provider allows you to: * **React to cohort changes in real-time** - Execute code when users enter or exit cohorts * **Observe activations** - Monitor when users qualify for specific ad platform activations * **Build personalized experiences** - Show/hide content based on cohort membership * **Implement A/B tests** - Dynamically segment users and track their behavior ## Creating a TriggersProvider Create a `TriggersProvider` instance from your Permutive SDK instance: ```kotlin Kotlin theme={"dark"} import com.permutive.android.TriggersProvider class MyActivity : AppCompatActivity() { private val permutive by lazy { (application as MyApplication).permutive } private val triggersProvider: TriggersProvider by lazy { permutive.triggersProvider() } // Use the triggers provider... } ``` ```java Java theme={"dark"} import com.permutive.android.TriggersProvider; public class MyActivity extends AppCompatActivity { private TriggersProvider triggersProvider; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); Permutive permutive = ((MyApplication) getApplication()).getPermutive(); triggersProvider = permutive.triggersProvider(); } } ``` > 💡 Lifecycle Management > > You can create any number of `TriggersProvider` instances. They're lightweight and don't maintain heavy state. *** ## Use Cases ### 1. Observing Cohort Membership Monitor when a user is in a specific cohort: ```kotlin Kotlin theme={"dark"} import com.permutive.android.TriggerAction class PersonalizedActivity : AppCompatActivity() { private var premiumContentTrigger: TriggerAction? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_personalized) val triggersProvider = permutive.triggersProvider() // Monitor if user is in the "premium_readers" cohort premiumContentTrigger = triggersProvider.triggerAction("premium_readers") { isInCohort -> if (isInCohort) { showPremiumContent() } else { showStandardContent() } } } override fun onDestroy() { super.onDestroy() // Clean up the trigger when the activity is destroyed premiumContentTrigger?.close() } private fun showPremiumContent() { // Update UI to show premium features binding.premiumBanner.visibility = View.VISIBLE binding.subscriptionPrompt.visibility = View.GONE } private fun showStandardContent() { // Update UI for standard users binding.premiumBanner.visibility = View.GONE binding.subscriptionPrompt.visibility = View.VISIBLE } } ``` ```java Java theme={"dark"} import com.permutive.android.TriggerAction; import com.permutive.android.internal.Method; public class PersonalizedActivity extends AppCompatActivity { private TriggerAction premiumContentTrigger; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_personalized); TriggersProvider triggersProvider = permutive.triggersProvider(); // Monitor if user is in the "premium_readers" cohort premiumContentTrigger = triggersProvider.triggerAction( "premium_readers", new Method() { @Override public void invoke(Boolean isInCohort) { if (isInCohort) { showPremiumContent(); } else { showStandardContent(); } } } ); } @Override protected void onDestroy() { super.onDestroy(); if (premiumContentTrigger != null) { premiumContentTrigger.close(); } } private void showPremiumContent() { // Update UI to show premium features } private void showStandardContent() { // Update UI for standard users } } ``` *** ### 2. Observing Multiple Cohorts React to multiple cohort memberships: #### Kotlin ```kotlin theme={"dark"} class ContentRecommendationActivity : AppCompatActivity() { private val triggers = mutableListOf() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val triggersProvider = permutive.triggersProvider() // Sports enthusiasts triggers.add( triggersProvider.triggerAction("sports_enthusiast") { isInCohort -> if (isInCohort) addRecommendation("Sports") } ) // Tech readers triggers.add( triggersProvider.triggerAction("tech_reader") { isInCohort -> if (isInCohort) addRecommendation("Technology") } ) // Business professionals triggers.add( triggersProvider.triggerAction("business_professional") { isInCohort -> if (isInCohort) addRecommendation("Business") } ) } override fun onDestroy() { super.onDestroy() triggers.forEach { it.close() } triggers.clear() } private fun addRecommendation(category: String) { // Update UI with personalized recommendations } } ``` *** ### 3. Observing Activations for Ad Platforms Monitor cohorts activated for specific ad platforms: #### Kotlin ```kotlin theme={"dark"} class AdTargetingActivity : AppCompatActivity() { private var gamActivationTrigger: TriggerAction? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val triggersProvider = permutive.triggersProvider() // Monitor Google Ad Manager activations gamActivationTrigger = triggersProvider.cohortActivations("dfp") { cohorts -> Log.d("Permutive", "User has ${cohorts.size} active GAM cohorts: $cohorts") updateAdTargeting(cohorts) } } override fun onDestroy() { super.onDestroy() gamActivationTrigger?.close() } private fun updateAdTargeting(cohorts: List) { // Use cohorts for ad targeting } } ``` #### Available Activation Types | Activation Type | Description | | -------------------------------- | ------------------------------------------------------------------- | | `"dfp"` | Google Ad Manager (formerly DoubleClick for Publishers) activations | | `"appnexus_adserver"` | Xandr/AppNexus ad server activations | | `"freewheel"` | Freewheel activations | | `"dfp_contextual"` | Google Ad Manager contextual cohorts | | `"appnexus_adserver_contextual"` | Xandr/AppNexus contextual cohorts | *** ### 4. A/B Testing Based on Cohorts Implement feature flags or A/B tests using cohort membership: #### Kotlin ```kotlin theme={"dark"} class ExperimentActivity : AppCompatActivity() { private var experimentTrigger: TriggerAction? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val triggersProvider = permutive.triggersProvider() // A/B test: Show new checkout flow to test cohort experimentTrigger = triggersProvider.triggerAction("checkout_experiment_v2") { isInTestGroup -> if (isInTestGroup) { showNewCheckoutFlow() } else { showStandardCheckoutFlow() } } } override fun onDestroy() { super.onDestroy() experimentTrigger?.close() } } ``` *** ## TriggerAction Lifecycle The `TriggerAction` interface represents an active trigger subscription. It's crucial to manage its lifecycle properly to prevent memory leaks. ### Key Points 1. **Create** triggers when you need to start observing 2. **Close** triggers when you're done (typically in `onDestroy()`) 3. **Store** references if you need to close them later 4. **Don't recreate** unnecessarily - triggers survive configuration changes if managed properly ### Best Practices #### ✅ Good: Proper Lifecycle Management ```kotlin theme={"dark"} class MyActivity : AppCompatActivity() { private var trigger: TriggerAction? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) trigger = triggersProvider.triggerAction("cohort_id") { /* ... */ } } override fun onDestroy() { super.onDestroy() trigger?.close() } } ``` #### ✅ Good: Using ViewModel for Configuration Changes ```kotlin theme={"dark"} class MyViewModel : ViewModel() { private var trigger: TriggerAction? = null fun observeCohort(triggersProvider: TriggersProvider) { if (trigger == null) { trigger = triggersProvider.triggerAction("cohort_id") { /* ... */ } } } override fun onCleared() { super.onCleared() trigger?.close() } } ``` #### ❌ Bad: Not Closing Triggers ```kotlin theme={"dark"} class MyActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Creates a new trigger every time, never closes the old ones triggersProvider.triggerAction("cohort_id") { /* ... */ } } // Memory leak! Triggers never closed } ``` *** ## Thread Safety The `TriggersProvider` and `TriggerAction` are thread-safe. Callbacks are delivered on a background thread, so if you need to update UI, use appropriate threading mechanisms: ```kotlin Kotlin theme={"dark"} private var trigger: TriggerAction? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) trigger = triggersProvider.triggerAction("cohort_id") { isInCohort -> // Callback is on background thread lifecycleScope.launch(Dispatchers.Main) { // Update UI on main thread if (isInCohort) { textView.text = "User is in cohort" } } } } ``` ```java Java theme={"dark"} private final Handler mainHandler = new Handler(Looper.getMainLooper()); private TriggerAction trigger; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); trigger = triggersProvider.triggerAction("cohort_id", new Method() { @Override public void invoke(Boolean isInCohort) { // Callback is on background thread mainHandler.post(() -> { // Update UI on main thread if (isInCohort) { textView.setText("User is in cohort"); } }); } }); } ``` *** ## Advanced Patterns ### Combining Multiple Cohorts Trigger actions only when user is in multiple cohorts: ```kotlin theme={"dark"} class AdvancedTargetingActivity : AppCompatActivity() { private var isPremium = false private var isSportsReader = false private val triggers = mutableListOf() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val triggersProvider = permutive.triggersProvider() triggers.add( triggersProvider.triggerAction("premium_subscriber") { inCohort -> isPremium = inCohort updateContent() } ) triggers.add( triggersProvider.triggerAction("sports_enthusiast") { inCohort -> isSportsReader = inCohort updateContent() } ) } private fun updateContent() { when { isPremium && isSportsReader -> showPremiumSportsContent() isPremium -> showPremiumGeneralContent() isSportsReader -> showFreeSportsContent() else -> showGeneralContent() } } override fun onDestroy() { super.onDestroy() triggers.forEach { it.close() } triggers.clear() } } ``` *** ## Deprecated APIs ### Legacy Segment-Based Triggers The following methods are deprecated as they only support integer-based segment IDs: ```kotlin theme={"dark"} @Deprecated("Use triggerAction(cohortId: String, callback: Method)") fun triggerAction(queryId: Int, callback: Method): TriggerAction @Deprecated("Use cohortActivations") fun querySegments(callback: Method>): TriggerAction @Deprecated("Use cohortActivations") fun queryReactions(reaction: String, callback: Method>): TriggerAction ``` **Migration Guide:** Old (Deprecated): ```kotlin theme={"dark"} triggersProvider.triggerAction(12345) { result: Boolean -> // Handle result } ``` New: ```kotlin theme={"dark"} triggersProvider.triggerAction("cohort_id_string") { isInCohort -> // Handle result } ``` > 📘 Why the Change? > > The SDK now supports Classification Model cohorts which use string IDs. The new APIs support both traditional integer-based cohorts and newer string-based cohorts seamlessly. *** ## Troubleshooting **Problem:** Your trigger callback is never invoked. **Possible Causes:** 1. SDK hasn't finished initializing 2. Cohort ID is incorrect 3. User hasn't generated enough events to be segmented **Solutions:** * Enable debug logging: `permutive.setDeveloperMode(true)` * Check logs for cohort updates * Verify cohort ID matches your dashboard configuration * Ensure events are being tracked (see [Verification Guide](/sdks/mobile/android/getting-started/verification)) **Problem:** App memory usage grows over time. **Cause:** `TriggerAction` instances not being closed. **Solution:** Always call `close()` on triggers in appropriate lifecycle methods (usually `onDestroy()` or `onCleared()`). **Problem:** Crash when trying to update UI from callback. **Cause:** Callbacks execute on background threads. **Solution:** Use `Handler`, coroutines, or `runOnUiThread()` to update UI (see Thread Safety section above). *** ## Best Practices * Close all triggers when done to prevent memory leaks * Handle threading appropriately when updating UI * Use descriptive cohort IDs that match your dashboard * Store trigger references if you need to close them later * Test with debug logging enabled * Create triggers and never close them * Update UI directly from callbacks without switching threads * Create multiple triggers for the same cohort unnecessarily * Assume callbacks will fire immediately (SDK needs time to initialize) *** ## Example: Complete Implementation Here's a complete example showing proper implementation: ```kotlin theme={"dark"} import androidx.appcompat.app.AppCompatActivity import androidx.lifecycle.lifecycleScope import com.permutive.android.TriggerAction import com.permutive.android.TriggersProvider import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch class PersonalizedHomeActivity : AppCompatActivity() { private val permutive by lazy { (application as MyApplication).permutive } private val triggersProvider by lazy { permutive.triggersProvider() } private val activeTriggers = mutableListOf() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_personalized_home) setupCohortTriggers() } private fun setupCohortTriggers() { // Premium content trigger activeTriggers.add( triggersProvider.triggerAction("premium_subscriber") { isSubscriber -> lifecycleScope.launch(Dispatchers.Main) { updatePremiumFeatures(isSubscriber) } } ) // Sports content trigger activeTriggers.add( triggersProvider.triggerAction("sports_enthusiast") { isSportsReader -> lifecycleScope.launch(Dispatchers.Main) { updateSportsRecommendations(isSportsReader) } } ) // Ad activations trigger activeTriggers.add( triggersProvider.cohortActivations("dfp") { cohorts -> lifecycleScope.launch(Dispatchers.Main) { updateAdTargeting(cohorts) } } ) } private fun updatePremiumFeatures(isPremium: Boolean) { binding.premiumBadge.visibility = if (isPremium) View.VISIBLE else View.GONE binding.upgradePrompt.visibility = if (isPremium) View.GONE else View.VISIBLE } private fun updateSportsRecommendations(showSports: Boolean) { if (showSports) { binding.sportsSection.visibility = View.VISIBLE loadSportsContent() } else { binding.sportsSection.visibility = View.GONE } } private fun updateAdTargeting(cohorts: List) { Log.d("Permutive", "Updated ad targeting with ${cohorts.size} cohorts") // Ad targeting logic here } private fun loadSportsContent() { // Load sports-specific content } override fun onDestroy() { super.onDestroy() // Clean up all triggers activeTriggers.forEach { it.close() } activeTriggers.clear() } } ``` *** ## Related Documentation Understanding how cohorts work How events feed into segmentation Tracking users across sessions Content-based segmentation *** ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ### Key Interfaces * `TriggersProvider` - Factory for creating trigger subscriptions * `TriggerAction` - Represents an active trigger subscription * `Method` - Callback interface for Java compatibility # Video Ad Tracking Source: https://docs.permutive.com/sdks/mobile/android/features/video-ad-tracking Track video advertisements, clicks, and completions The `AdTracker` API allows you to track video advertisement events. Use this to measure ad views, engagement, clicks, and completions within video content. **Android is the only Permutive SDK with a native ad tracker.** iOS / tvOS and Web CTV publishers emit ad events manually via `track(...)`. The typed `AdTracker` lifecycle below is unique to Android — use it instead of generic `track()` calls so the emitted events match the canonical schema automatically. ## Overview `AdTracker` provides comprehensive video ad tracking: * **Automatic lifecycle tracking** - Tracks VideoAdView and VideoAdCompletion events * **Engagement metrics** - Measures time spent watching ads * **Click tracking** - Tracks ad interactions * **Custom events** - Track custom ad-related events * **Shared context** - Can share View ID with parent MediaTracker *** ## Creating an AdTracker AdTracker can be created in two ways: ### 1. From MediaTracker (Recommended) Use this when the ad is related to video content currently being viewed. The AdTracker will share the same View ID with the MediaTracker: ```kotlin theme={"dark"} val videoTracker = permutive.trackVideoView(...) val adTracker = videoTracker.trackAdView( durationMs = 15000, // 15 second ad adProperties = AdTracker.AdProperties( title = "Product Advertisement", durationInSeconds = 15, isMuted = false, campaignId = "camp_123", creativeId = "creative_456" ) ) ``` ### 2. Standalone AdTracker Use this for standalone video ads not associated with specific video content: ```kotlin theme={"dark"} val adTracker = permutive.trackVideoAdView( durationMs = 30000, // 30 second ad adProperties = AdTracker.AdProperties( title = "Standalone Ad", durationInSeconds = 30, isMuted = false, campaignId = "camp_789", creativeId = "creative_012" ) ) ``` *** ## Ad Events AdTracker automatically generates these events: ### 1. VideoAdView Event Tracked when AdTracker is created: ``` Event: VideoAdView Properties: - [ad properties] - [custom properties] ``` ### 2. VideoAdCompletion Event Tracked when `completion()` is called: ``` Event: VideoAdCompletion Properties: - engaged_time: Time spent watching ad (seconds) - completion: Percentage of ad viewed (0.0 - 1.0) - [ad properties] - [custom properties] ``` ### 3. VideoAdClicked Event Tracked when `clicked()` is called: ``` Event: VideoAdClicked Properties: - [ad properties] - [custom properties] ``` *** ## AdTracker Methods ### play() Call when the ad starts playing. AdTracker initializes in a paused state, so call this immediately if the ad auto-plays: ```kotlin theme={"dark"} adTracker.play() ``` ### play(positionMs) Call when playback position changes (e.g., seeking): ```kotlin theme={"dark"} adTracker.play(positionMs = 5000) // Resume at 5 seconds ``` ### pause() Call when the ad is paused or buffering: ```kotlin theme={"dark"} adTracker.pause() ``` ### clicked() Call when the user clicks on the ad. This tracks a **VideoAdClicked** event: ```kotlin theme={"dark"} adTracker.clicked() ``` ### completion() Call when the ad is no longer being shown. This tracks a **VideoAdCompletion** event with engagement properties: ```kotlin theme={"dark"} adTracker.completion() ``` > ⚠️ Important > > Once `completion()` is called, the AdTracker is closed and subsequent method calls will have no effect. ### Custom Events Track custom ad-related events: ```kotlin theme={"dark"} // Track without additional properties adTracker.trackWithAdProperties("AdMuted") // Track with additional properties adTracker.trackWithAdProperties( "AdQualityChanged", EventProperties.from( "from_quality" to "480p", "to_quality" to "720p" ) ) ``` *** ## Ad Properties ### Standard Ad Properties ```kotlin theme={"dark"} AdTracker.AdProperties( title = "Ad Title", durationInSeconds = 30, isMuted = false, campaignId = "campaign_abc123", creativeId = "creative_xyz789" ) ``` ### Property Reference | Property | Type | Description | | --------------------- | ------- | ------------------------ | | **title** | String | Ad title or name | | **durationInSeconds** | Int | Ad duration in seconds | | **isMuted** | Boolean | Whether ad started muted | | **campaignId** | String | Ad campaign identifier | | **creativeId** | String | Ad creative identifier | All properties are passed to every event tracked through the AdTracker. *** ## Complete Example ### Kotlin - Pre-Roll Ad ```kotlin theme={"dark"} import com.permutive.android.MediaTracker import com.permutive.android.AdTracker import com.permutive.android.EventProperties class VideoFragment : Fragment() { private val permutive by lazy { (requireActivity().application as MyApplication).permutive } private lateinit var videoTracker: MediaTracker private lateinit var adTracker: AdTracker private lateinit var exoPlayer: ExoPlayer override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { // Create video tracker videoTracker = permutive.trackVideoView( durationMilliseconds = 180000, // 3 minute video videoProperties = MediaTracker.VideoProperties( title = "Main Video Content" ) ) // Create ad tracker for pre-roll ad adTracker = videoTracker.trackAdView( durationMs = 15000, // 15 second ad adProperties = AdTracker.AdProperties( title = "Pre-Roll Advertisement", durationInSeconds = 15, isMuted = false, campaignId = "preroll_camp_123", creativeId = "creative_456" ) ) setupAdPlayer() return inflater.inflate(R.layout.fragment_video, container, false) } private fun setupAdPlayer() { exoPlayer = ExoPlayer.Builder(requireContext()).build() // Load ad content val adUri = Uri.parse("https://example.com/ad.mp4") val adMediaItem = MediaItem.fromUri(adUri) exoPlayer.setMediaItem(adMediaItem) exoPlayer.prepare() // Track ad playback exoPlayer.addListener(object : Player.Listener { override fun onIsPlayingChanged(isPlaying: Boolean) { if (isPlaying) { adTracker.play() } else { adTracker.pause() } } override fun onPlaybackStateChanged(state: Int) { when (state) { Player.STATE_ENDED -> { // Ad finished adTracker.completion() // Now load main video content loadMainVideoContent() } Player.STATE_BUFFERING -> { adTracker.pause() } } } }) // Track ad clicks playerView.setOnClickListener { adTracker.clicked() openAdLandingPage() } // Start ad playback exoPlayer.play() } private fun loadMainVideoContent() { // Load main video val videoUri = Uri.parse("https://example.com/video.mp4") val videoMediaItem = MediaItem.fromUri(videoUri) exoPlayer.setMediaItem(videoMediaItem) exoPlayer.prepare() exoPlayer.play() // Now track main video with videoTracker videoTracker.play() } private fun openAdLandingPage() { val intent = Intent(Intent.ACTION_VIEW, Uri.parse("https://advertiser.com/landing")) startActivity(intent) } override fun onDestroy() { super.onDestroy() videoTracker.stop() exoPlayer.release() } } ``` ### Java - Pre-Roll Ad ```java theme={"dark"} import com.permutive.android.MediaTracker; import com.permutive.android.AdTracker; public class VideoFragment extends Fragment { private MediaTracker videoTracker; private AdTracker adTracker; private ExoPlayer exoPlayer; @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { Permutive permutive = ((MyApplication) requireActivity().getApplication()).getPermutive(); // Create video tracker MediaTracker.VideoProperties videoProps = new MediaTracker.VideoProperties.Builder() .title("Main Video Content") .build(); videoTracker = permutive.trackVideoView( 180000, // 3 minutes videoProps, null, null ); // Create ad tracker AdTracker.AdProperties adProps = new AdTracker.AdProperties( "Pre-Roll Advertisement", 15, // 15 seconds false, // not muted "preroll_camp_123", "creative_456" ); adTracker = videoTracker.trackAdView(15000, adProps); setupAdPlayer(); return inflater.inflate(R.layout.fragment_video, container, null); } private void setupAdPlayer() { exoPlayer = new ExoPlayer.Builder(requireContext()).build(); // Load ad Uri adUri = Uri.parse("https://example.com/ad.mp4"); MediaItem adMediaItem = MediaItem.fromUri(adUri); exoPlayer.setMediaItem(adMediaItem); exoPlayer.prepare(); // Track ad playback exoPlayer.addListener(new Player.Listener() { @Override public void onIsPlayingChanged(boolean isPlaying) { if (isPlaying) { adTracker.play(); } else { adTracker.pause(); } } @Override public void onPlaybackStateChanged(int state) { if (state == Player.STATE_ENDED) { adTracker.completion(); loadMainVideoContent(); } else if (state == Player.STATE_BUFFERING) { adTracker.pause(); } } }); // Track clicks playerView.setOnClickListener(v -> { adTracker.clicked(); openAdLandingPage(); }); exoPlayer.play(); } private void loadMainVideoContent() { Uri videoUri = Uri.parse("https://example.com/video.mp4"); MediaItem videoMediaItem = MediaItem.fromUri(videoUri); exoPlayer.setMediaItem(videoMediaItem); exoPlayer.prepare(); exoPlayer.play(); videoTracker.play(); } private void openAdLandingPage() { Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse("https://advertiser.com/landing")); startActivity(intent); } @Override public void onDestroy() { super.onDestroy(); videoTracker.stop(); exoPlayer.release(); } } ``` *** ## Use Cases Ad shown **before** video content starts: ```kotlin theme={"dark"} // Create video tracker first val videoTracker = permutive.trackVideoView(...) // Create ad tracker from video tracker val preRollAd = videoTracker.trackAdView( durationMs = 15000, adProperties = AdTracker.AdProperties( title = "Pre-Roll Ad", durationInSeconds = 15, campaignId = "preroll_123" ) ) // Play ad preRollAd.play() // ... ad plays ... preRollAd.completion() // Then play main video videoTracker.play() ``` Ad shown **during** video content: ```kotlin theme={"dark"} // Main video playing videoTracker.pause() // Create mid-roll ad val midRollAd = videoTracker.trackAdView( durationMs = 30000, adProperties = AdTracker.AdProperties( title = "Mid-Roll Ad", durationInSeconds = 30, campaignId = "midroll_456" ) ) midRollAd.play() // ... ad plays ... midRollAd.completion() // Resume main video videoTracker.play() ``` Ad **not associated** with video content: ```kotlin theme={"dark"} // Ad not associated with video content val standaloneAd = permutive.trackVideoAdView( durationMs = 30000, adProperties = AdTracker.AdProperties( title = "Standalone Video Ad", durationInSeconds = 30, campaignId = "standalone_789" ) ) standaloneAd.play() // ... ad plays ... standaloneAd.completion() ``` **Multiple ads** played in sequence: ```kotlin theme={"dark"} val ads = listOf( AdInfo("Ad 1", 15000, "camp_1", "creative_1"), AdInfo("Ad 2", 15000, "camp_2", "creative_2"), AdInfo("Ad 3", 30000, "camp_3", "creative_3") ) ads.forEach { adInfo -> val adTracker = videoTracker.trackAdView( durationMs = adInfo.duration, adProperties = AdTracker.AdProperties( title = adInfo.title, durationInSeconds = adInfo.duration / 1000, campaignId = adInfo.campaignId, creativeId = adInfo.creativeId ) ) // Play ad adTracker.play() // ... wait for completion ... adTracker.completion() } ``` *** ## Tracking Ad Interactions ### Click Tracking ```kotlin theme={"dark"} // User clicks ad adClickArea.setOnClickListener { adTracker.clicked() // Tracks VideoAdClicked event openAdvertiserUrl() } ``` ### Skip Tracking The canonical schema defines `VideoAdView`, `VideoAdEngagement`, `VideoAdCompletion`, and `VideoAdClicked` — there is no standard "skipped" event. If you want to capture skips, emit a custom event via `trackWithAdProperties(...)` and add the event name to your workspace schema: ```kotlin theme={"dark"} // User skips ad (custom event — register the name in your workspace schema) skipButton.setOnClickListener { adTracker.trackWithAdProperties( "VideoAdSkipped", EventProperties.from( "time_watched_seconds" to getWatchedTime() ) ) adTracker.completion() loadMainContent() } ``` ### Error Tracking Errors are likewise not in the standard schema — emit a custom event if you need to capture ad-load failures: ```kotlin theme={"dark"} // Ad fails to load (custom event — register the name in your workspace schema) adPlayer.setErrorListener { error -> adTracker.trackWithAdProperties( "VideoAdError", EventProperties.from( "error_code" to error.code, "error_message" to error.message ) ) adTracker.completion() } ``` *** ## Troubleshooting **Problem:** VideoAdCompletion events not appearing. **Cause:** `completion()` not called. **Solution:** Always call `completion()` when ad finishes: ```kotlin theme={"dark"} // When ad ends adTracker.completion() ``` **Problem:** Ad events have same View ID as video. **Cause:** This is expected when creating AdTracker from MediaTracker. **This is correct behavior** - it links ad to video content. For independent tracking, use standalone AdTracker: ```kotlin theme={"dark"} // Standalone (separate View ID) val adTracker = permutive.trackVideoAdView(...) ``` **Problem:** Engaged time is wrong. **Causes:** 1. Not calling `play()` when ad starts 2. Not calling `pause()` for buffering **Solution:** Track all state changes: ```kotlin theme={"dark"} player.addListener(object : Player.Listener { override fun onIsPlayingChanged(isPlaying: Boolean) { if (isPlaying) adTracker.play() else adTracker.pause() } }) ``` **Problem:** Multiple VideoAdCompletion events tracked. **Cause:** Calling `completion()` multiple times. **Solution:** Call `completion()` only once. After calling it, AdTracker is closed. See [Common Errors](/sdks/mobile/android/troubleshooting/common-errors) for more troubleshooting. *** ## Best Practices * Always call `completion()` when ad finishes * Track play/pause accurately * Use `clicked()` for click tracking * Create from MediaTracker for in-content ads * Provide campaign and creative IDs * Call `play()` immediately if ad auto-plays * Forget to call `completion()` * Call methods after `completion()` * Skip play/pause lifecycle events * Use standalone tracker for in-content ads *** ## Related Documentation Track video content Custom properties Track pages Solve common issues *** ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ### AdTracker Interface * `play()` - Start/resume ad playback * `play(positionMs: Long)` - Start at specific position * `pause()` - Pause ad playback * `clicked()` - Track ad click (sends VideoAdClicked event) * `completion()` - Complete ad tracking (sends VideoAdCompletion event) * `trackWithAdProperties(eventName: String)` - Track custom event with ad properties * `trackWithAdProperties(eventName: String, customProperties: EventProperties)` - Track custom event with ad and custom properties ### Creating AdTracker * `MediaTracker.trackAdView(durationMs: Long, adProperties: AdTracker.AdProperties?)` - Create from MediaTracker (shares View ID) * `Permutive.trackVideoAdView(durationMs: Long, adProperties: AdTracker.AdProperties?, pageProperties: MediaTracker.PageProperties?, customEventProperties: EventProperties? = null)` - Create standalone AdTracker ### AdProperties * `AdTracker.AdProperties(title, durationInSeconds, isMuted, campaignId, creativeId)` - Ad property container # Video Tracking Source: https://docs.permutive.com/sdks/mobile/android/features/video-tracking Track video playback, engagement, and completion metrics The `MediaTracker` API allows you to track video content events with Permutive. Use this for tracking video playback, engagement, and completion metrics. **Connected TV Integration** Video event tracking described below is available once the connected TV integration has been enabled. Please contact your Customer Success Manager (CSM) to enable this feature. ## Overview `MediaTracker` provides comprehensive video tracking capabilities: * **Automatic lifecycle tracking** - Tracks Videoview and VideoCompletion events * **Engagement metrics** - Measures time spent watching and completion percentage * **Custom events** - Track custom video-related events * **Rich metadata** - Support for extensive video properties *** ## Video Events MediaTracker automatically tracks two event types: ### 1. Videoview Event Tracked when MediaTracker is created: ``` Event: Videoview Properties: - [your custom properties] - [standard video properties] ``` ### 2. VideoCompletion Event Tracked when video is stopped: ``` Event: VideoCompletion Properties: - aggregations.VideoEngagement.engaged_time: Total time spent watching (seconds) - aggregations.VideoEngagement.completion: Percentage of video viewed (0.0 - 1.0) - [your custom properties] - [standard video properties] ``` > 📘 Note > > The `aggregations.VideoEngagement.completion` property requires a known duration to be set. Pass `durationMilliseconds` when creating the MediaTracker. *** ## Basic Usage ### Creating a MediaTracker Create a MediaTracker when video playback begins: ```kotlin Kotlin theme={"dark"} import com.permutive.android.MediaTracker import android.net.Uri class VideoActivity : AppCompatActivity() { private val permutive by lazy { (application as MyApplication).permutive } private lateinit var videoTracker: MediaTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) videoTracker = permutive.trackVideoView( durationMilliseconds = 120000, // 2 minutes videoProperties = MediaTracker.VideoProperties( title = "Sample Video", genre = listOf("Documentary"), contentType = listOf("Education"), runtime = 120 ) ) } override fun onDestroy() { super.onDestroy() videoTracker.stop() // Important: Always stop to send VideoCompletion } } ``` ```java Java theme={"dark"} import com.permutive.android.MediaTracker; import android.net.Uri; public class VideoActivity extends AppCompatActivity { private MediaTracker videoTracker; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); Permutive permutive = ((MyApplication) getApplication()).getPermutive(); MediaTracker.VideoProperties videoProps = new MediaTracker.VideoProperties.Builder() .title("Sample Video") .genre(Arrays.asList("Documentary")) .contentType(Arrays.asList("Education")) .runtime(120) .build(); videoTracker = permutive.trackVideoView( 120000, // 2 minutes in milliseconds videoProps, null, // pageProperties (optional) null // customEventProperties (optional) ); } @Override protected void onDestroy() { super.onDestroy(); videoTracker.stop(); // Important: Always stop to send VideoCompletion } } ``` *** ## MediaTracker Lifecycle ### Expected Usage Flow 1. **Create** MediaTracker instance with properties 2. **Call** `play()` when playback begins 3. **Track buffering** with `pause()` / `play()` 4. **Track scrubbing** with `play(position)` 5. **Call** `stop()` when playback completes > ⚠️ Single Instance Limitation > > Only a single instance of `PageTracker` or `MediaTracker` is available at any time. Close existing trackers before creating new ones. ### Playback Control Methods #### play() Call when video starts playing: ```kotlin theme={"dark"} videoTracker.play() ``` #### play(positionMs) Call when playback position changes (e.g., seeking): ```kotlin theme={"dark"} videoTracker.play(positionMs = 30000) // Seek to 30 seconds ``` #### pause() Call when video is paused or buffering: ```kotlin theme={"dark"} videoTracker.pause() ``` #### stop() Call when video playback completes or user exits: ```kotlin theme={"dark"} videoTracker.stop() // Sends VideoCompletion event ``` > ⚠️ Important: Always Call stop() > > Failing to call `stop()` will prevent VideoCompletion events from being tracked. *** ## Video Properties ### Standard Video Properties The SDK provides standard video properties for consistent tracking: ```kotlin theme={"dark"} MediaTracker.VideoProperties( title = "Video Title", genre = listOf("Action", "Thriller"), contentType = listOf("Movie", "Feature"), ageRating = "PG-13", runtime = 7200, // Runtime in seconds country = "US", originalLanguage = "en", audioLanguage = "en", areSubtitlesEnabled = true, subtitlesLanguage = "en", seasonNumber = 1, episodeNumber = 5, consecutiveEpisodes = 3, iabCategories = listOf("IAB1", "IAB2") ) ``` ### Property Reference These are the Kotlin SDK parameter names. The SDK maps them to the `snake_case` event schema and nests them under the `video` parent automatically. | Property | Type | Schema Name | Description | | ----------------------- | ------------- | ---------------------------- | --------------------------------------- | | **title** | String | `video.title` | Video title | | **genre** | List\ | `video.genre` | Video genres (e.g., "Drama", "Comedy") | | **contentType** | List\ | `video.content_type` | Content types (e.g., "Movie", "Series") | | **ageRating** | String | `video.age_rating` | Age rating (e.g., "PG-13", "TV-MA") | | **runtime** | Int | `video.runtime` | Runtime in **seconds** | | **country** | String | `video.country` | Origin country | | **originalLanguage** | String | `video.original_language` | Original language code | | **audioLanguage** | String | `video.audio_language` | Audio language code | | **areSubtitlesEnabled** | Boolean | `video.subtitles.enabled` | Whether subtitles are enabled | | **subtitlesLanguage** | String | `video.subtitles.language` | Subtitle language code | | **seasonNumber** | Int | `video.season_number` | Season number (for series) | | **episodeNumber** | Int | `video.episode_number` | Episode number (for series) | | **consecutiveEpisodes** | Int | `video.consecutive_episodes` | Consecutive episodes watched | | **iabCategories** | List\ | `video.iab_categories` | IAB content taxonomy categories | > 💡 Best Practice > > Track as many properties as possible to enable richer cohort creation and insights. *** ## Page Properties (Optional) If the video is displayed within a page context (e.g., embedded in article), include page properties: ```kotlin theme={"dark"} videoTracker = permutive.trackVideoView( durationMilliseconds = 120000, videoProperties = MediaTracker.VideoProperties( title = "Tutorial Video" ), pageProperties = MediaTracker.PageProperties( title = "How to Use Android SDK", url = Uri.parse("https://example.com/tutorial"), referrer = Uri.parse("https://example.com/docs") ) ) ``` ### PageProperties Reference | Property | Type | Description | | ------------ | ------ | ------------------ | | **title** | String | Page title | | **url** | Uri | Page URL | | **referrer** | Uri | Referring page URL | *** ## Custom Properties Add custom properties specific to your event schema: ```kotlin theme={"dark"} import com.permutive.android.EventProperties videoTracker = permutive.trackVideoView( durationMilliseconds = 120000, videoProperties = videoProps, pageProperties = null, customEventProperties = EventProperties.from( "video_id" to "vid_12345", "playlist_id" to "playlist_abc", "is_premium_content" to true, "content_partner" to "PartnerXYZ" ) ) ``` *** ## Complete Example ```kotlin Kotlin theme={"dark"} import com.permutive.android.MediaTracker import android.net.Uri import androidx.appcompat.app.AppCompatActivity class VideoPlayerFragment : Fragment() { private val permutive by lazy { (requireActivity().application as MyApplication).permutive } private lateinit var videoTracker: MediaTracker private lateinit var exoPlayer: ExoPlayer override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { // Initialize video tracker videoTracker = permutive.trackVideoView( durationMilliseconds = 180000, // 3 minutes videoProperties = MediaTracker.VideoProperties( title = "Introduction to Android", genre = listOf("Educational", "Technology"), contentType = listOf("Tutorial"), ageRating = "G", runtime = 180, country = "US", originalLanguage = "en", audioLanguage = "en", areSubtitlesEnabled = false, iabCategories = listOf("IAB19") ), pageProperties = MediaTracker.PageProperties( title = "Android Tutorial Page", url = Uri.parse("https://example.com/tutorials/android"), referrer = Uri.parse("https://example.com/home") ), customEventProperties = EventProperties.from( "video_id" to "vid_tutorial_001", "is_premium" to false ) ) // Set up ExoPlayer with tracking setupVideoPlayer() return inflater.inflate(R.layout.fragment_video, container, false) } private fun setupVideoPlayer() { exoPlayer = ExoPlayer.Builder(requireContext()).build() exoPlayer.addListener(object : Player.Listener { override fun onPlaybackStateChanged(state: Int) { when (state) { Player.STATE_READY -> { // Video ready to play if (exoPlayer.isPlaying) { videoTracker.play() } } Player.STATE_BUFFERING -> { videoTracker.pause() } } } override fun onIsPlayingChanged(isPlaying: Boolean) { if (isPlaying) { videoTracker.play() } else { videoTracker.pause() } } }) // Track position updates exoPlayer.addAnalyticsListener(object : AnalyticsListener { override fun onPositionDiscontinuity( eventTime: AnalyticsListener.EventTime, reason: Int ) { if (reason == Player.DISCONTINUITY_REASON_SEEK) { videoTracker.play(exoPlayer.currentPosition) } } }) } override fun onPause() { super.onPause() videoTracker.pause() exoPlayer.pause() } override fun onResume() { super.onResume() if (exoPlayer.isPlaying) { videoTracker.play() } } override fun onDestroy() { super.onDestroy() videoTracker.stop() // Send VideoCompletion event exoPlayer.release() } } ``` ```java Java theme={"dark"} import com.permutive.android.MediaTracker; import android.net.Uri; public class VideoPlayerFragment extends Fragment { private MediaTracker videoTracker; private ExoPlayer exoPlayer; @Override public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { Permutive permutive = ((MyApplication) requireActivity().getApplication()).getPermutive(); // Build video properties MediaTracker.VideoProperties videoProps = new MediaTracker.VideoProperties.Builder() .title("Introduction to Android") .genre(Arrays.asList("Educational", "Technology")) .contentType(Arrays.asList("Tutorial")) .ageRating("G") .runtime(180) .country("US") .originalLanguage("en") .audioLanguage("en") .areSubtitlesEnabled(false) .iabCategories(Arrays.asList("IAB19")) .build(); // Build page properties MediaTracker.PageProperties pageProps = new MediaTracker.PageProperties( "Android Tutorial Page", Uri.parse("https://example.com/tutorials/android"), Uri.parse("https://example.com/home") ); // Build custom properties EventProperties customProps = new EventProperties.Builder() .with("video_id", "vid_tutorial_001") .with("is_premium", false) .build(); // Create video tracker videoTracker = permutive.trackVideoView( 180000, // 3 minutes videoProps, pageProps, customProps ); setupVideoPlayer(); return inflater.inflate(R.layout.fragment_video, container, null); } private void setupVideoPlayer() { exoPlayer = new ExoPlayer.Builder(requireContext()).build(); exoPlayer.addListener(new Player.Listener() { @Override public void onPlaybackStateChanged(int state) { if (state == Player.STATE_READY && exoPlayer.isPlaying()) { videoTracker.play(); } else if (state == Player.STATE_BUFFERING) { videoTracker.pause(); } } @Override public void onIsPlayingChanged(boolean isPlaying) { if (isPlaying) { videoTracker.play(); } else { videoTracker.pause(); } } }); } @Override public void onPause() { super.onPause(); videoTracker.pause(); exoPlayer.pause(); } @Override public void onResume() { super.onResume(); if (exoPlayer.isPlaying()) { videoTracker.play(); } } @Override public void onDestroy() { super.onDestroy(); videoTracker.stop(); exoPlayer.release(); } } ``` *** ## Tracking Custom Events Track custom video-related events using the `track()` method: ```kotlin theme={"dark"} // User shares video videoTracker.track( "VideoShared", EventProperties.from( "share_method" to "twitter", "video_position_seconds" to 45 ) ) // User adds to favorites videoTracker.track("VideoAddedToFavorites") // Quality changed videoTracker.track( "VideoQualityChanged", EventProperties.from( "from_quality" to "720p", "to_quality" to "1080p" ) ) ``` *** ## Video Ad Tracking If you need to track video ads within video content, use the `AdTracker` API: ```kotlin theme={"dark"} // Create ad tracker from video tracker val adTracker = videoTracker.trackAdView( durationMs = 15000, // 15 second ad adProperties = AdTracker.AdProperties( title = "Product Ad", durationInSeconds = 15, isMuted = false, campaignId = "campaign_123", creativeId = "creative_456" ) ) // Track ad playback adTracker.play() // ... ad plays ... adTracker.completion() ``` See [Video Ad Tracking](/sdks/mobile/android/features/video-ad-tracking) for complete documentation. *** ## Use Cases ```kotlin theme={"dark"} videoTracker = permutive.trackVideoView( durationMilliseconds = movieDurationMs, videoProperties = MediaTracker.VideoProperties( title = movie.title, genre = movie.genres, contentType = listOf("Movie", "Feature"), ageRating = movie.rating, runtime = movie.runtimeSeconds, country = movie.country, originalLanguage = movie.language, iabCategories = movie.iabCategories ) ) ``` ```kotlin theme={"dark"} videoTracker = permutive.trackVideoView( durationMilliseconds = tutorialDurationMs, videoProperties = MediaTracker.VideoProperties( title = tutorial.title, genre = listOf("Educational"), contentType = listOf("Tutorial"), runtime = tutorial.runtimeSeconds ), customEventProperties = EventProperties.from( "course_id" to tutorial.courseId, "module_id" to tutorial.moduleId, "difficulty_level" to tutorial.difficulty ) ) ``` ```kotlin theme={"dark"} videoTracker = permutive.trackVideoView( durationMilliseconds = episodeDurationMs, videoProperties = MediaTracker.VideoProperties( title = episode.title, genre = series.genres, contentType = listOf("Series", "Episode"), seasonNumber = episode.season, episodeNumber = episode.number, consecutiveEpisodes = userWatchData.consecutiveCount, runtime = episode.runtimeSeconds ) ) ``` *** ## Troubleshooting **Problem:** VideoCompletion events not appearing. **Cause:** `stop()` not called. **Solution:** Always call `stop()` in `onDestroy()`: ```kotlin theme={"dark"} override fun onDestroy() { super.onDestroy() videoTracker.stop() // REQUIRED } ``` **Problem:** Engaged time is inaccurate. **Causes:** 1. Not calling `play()` when video plays 2. Not calling `pause()` when video pauses/buffers **Solution:** Track all play/pause events: ```kotlin theme={"dark"} exoPlayer.addListener(object : Player.Listener { override fun onIsPlayingChanged(isPlaying: Boolean) { if (isPlaying) { videoTracker.play() } else { videoTracker.pause() } } }) ``` **Problem:** `completion` property is missing or null. **Cause:** Duration not provided when creating MediaTracker. **Solution:** Always provide `durationMilliseconds`: ```kotlin theme={"dark"} videoTracker = permutive.trackVideoView( durationMilliseconds = videoDurationMs // REQUIRED for completion ) ``` **Problem:** Error about multiple trackers. **Cause:** Creating new PageTracker or MediaTracker without closing existing one. **Solution:** Close existing tracker first: ```kotlin theme={"dark"} // Close old tracker videoTracker.stop() // Now create new tracker videoTracker = permutive.trackVideoView(...) ``` See [Common Errors](/sdks/mobile/android/troubleshooting/common-errors) for more troubleshooting. *** ## Best Practices * Always call `stop()` when video finishes * Provide duration for completion tracking * Track play/pause events accurately * Include as many video properties as possible * Close tracker before creating a new one * Track buffering with pause/play * Forget to call `stop()` * Create multiple MediaTrackers simultaneously * Skip play/pause lifecycle events * Omit video duration *** ## Related Documentation Track video advertisements Track non-video content Custom properties Solve common issues *** ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ### MediaTracker Interface * `play()` - Start/resume video playback * `play(positionMs: Long)` - Start at specific position * `pause()` - Pause video playback * `stop()` - Complete video tracking (sends VideoCompletion) * `setDuration(durationMs: Long)` - Update video duration * `track(eventName: String)` - Track custom event * `track(eventName: String, properties: EventProperties)` - Track custom event with properties * `trackAdView(...)` - Create AdTracker for video ad ### Creating MediaTracker * `Permutive.trackVideoView(durationMilliseconds, videoProperties, pageProperties, customEventProperties)` - Create MediaTracker # SDK Initialization Source: https://docs.permutive.com/sdks/mobile/android/getting-started/initialization Initialize the Permutive SDK in your Android application The Permutive SDK must be initialized before you can track events or use any SDK features. This guide shows you how to properly initialize the SDK. **Prerequisites:** * SDK dependencies added to your project ([Installation Guide](/sdks/mobile/android/getting-started/installation)) * **Workspace ID** and **API Key** from your Permutive dashboard * Your project enabled for Android by Permutive The Permutive object should be created **only once** as a singleton. Initialize in your Application class: ```kotlin Kotlin theme={"dark"} import android.app.Application import com.permutive.android.Permutive import java.util.UUID class MyApplication : Application() { // Create a single instance using lazy initialization val permutive by lazy { Permutive( context = this, workspaceId = UUID.fromString("YOUR_WORKSPACE_ID"), apiKey = UUID.fromString("YOUR_API_KEY") ) } override fun onCreate() { super.onCreate() // SDK will initialize when first accessed } } ``` ```java Java theme={"dark"} import android.app.Application; import com.permutive.android.Permutive; import java.util.UUID; public class MyApplication extends Application { private Permutive permutive; // Create a single instance using double-checked locking public Permutive getPermutive() { if (permutive == null) { synchronized (this) { if (permutive == null) { permutive = new Permutive.Builder() .context(this) .workspaceId(UUID.fromString("YOUR_WORKSPACE_ID")) .apiKey(UUID.fromString("YOUR_API_KEY")) .build(); } } } return permutive; } } ``` Set user identity during initialization: ```kotlin Kotlin theme={"dark"} import com.permutive.android.Alias // Single identity with default tag val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, identity = "user_12345" ) // Or with multiple aliases: val customAliases = listOf( Alias.create( tag = "email_sha256", identity = "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e", priority = 0 ), Alias.create( tag = "internal_id", identity = "user_12345", priority = 1 ) ) val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, customAliases = customAliases ) ``` ```java Java theme={"dark"} import com.permutive.android.Alias; // Single identity Permutive permutive = new Permutive.Builder() .context(this) .workspaceId(YOUR_WORKSPACE_ID) .apiKey(YOUR_API_KEY) .identity("user_12345") .build(); // Multiple aliases Permutive permutive = new Permutive.Builder() .context(this) .workspaceId(YOUR_WORKSPACE_ID) .apiKey(YOUR_API_KEY) .customAlias(Alias.create("email_sha256", "f660ab912ec121d...", 0)) .customAlias(Alias.create("internal_id", "user_12345", 1)) .build(); ``` See [Identity Management](/sdks/mobile/android/core-concepts/identity-management) for details. Use alias providers for automatic identity management: ```kotlin Kotlin theme={"dark"} import com.permutive.android.aaid.AaidAliasProvider val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, aliasProviders = listOf(AaidAliasProvider(this)) ) ``` ```java Java theme={"dark"} import com.permutive.android.aaid.AaidAliasProvider; Permutive permutive = new Permutive.Builder() .context(this) .workspaceId(YOUR_WORKSPACE_ID) .apiKey(YOUR_API_KEY) .aliasProvider(new AaidAliasProvider(this)) .build(); ``` AAID requires the `google-ads` add-on and `AD_ID` permission. See [AAID Integration](/sdks/mobile/android/integrations/aaid-provider). ## Important Considerations Creating multiple Permutive instances will result in undefined behavior. Always use a singleton pattern. **Good:** ```kotlin theme={"dark"} class MyApplication : Application() { val permutive by lazy { Permutive(...) } // Single instance } ``` **Bad:** ```kotlin theme={"dark"} class MyActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { val permutive = Permutive(...) // NEW instance every time - DON'T! } } ``` * **Initialization is fast** - No significant impact on app startup * **No main thread blocking** - Network calls happen asynchronously * **Start tracking immediately** - No need to wait for initialization to complete We **strongly** recommend that you do **not** instantiate the Permutive object when receiving a push notification, but rather when the user interacts with the push notification. This prevents unnecessary SDK initialization from background processes. As a data controller, you may need to receive consent from the user before tracking data against them. The Permutive SDK assumes that at the time it is initialized, this consent has already been granted. **Coming Soon:** GDPR Compliance documentation is being developed. Contact your Customer Success Manager for immediate assistance. ## Troubleshooting **Symptoms:** ``` D/Permutive: Error fetching configuration - please check that your workspace id & API key is correct ``` **Solutions:** 1. Verify credentials are correct UUIDs 2. Ensure using `workspaceId` (not deprecated `projectId`) 3. Contact your Customer Success Manager to verify Android is enabled 4. Check device network connectivity **Causes:** 1. Invalid UUID format 2. Context is null 3. ProGuard/R8 stripping required classes **Solutions:** 1. Verify UUID format: `"550e8400-e29b-41d4-a716-446655440000"` 2. Use Application context (not Activity) 3. Check ProGuard rules are applied ## Next Steps Start tracking user interactions Confirm everything is working Track users across sessions Solutions to common issues ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). **Key Classes:** * `Permutive` - Main SDK class * `Permutive.Builder` - Builder for Java * `Alias` - User identity alias * `AliasProvider` - Automatic alias provider interface # Installation Source: https://docs.permutive.com/sdks/mobile/android/getting-started/installation Install the Permutive Android SDK and optional add-ons The Android SDK is comprised of the core SDK, and optional add-on libraries integrating with other 3rd party SDKs. ## Requirements | Requirement | Version | | ----------- | -------------------------- | | Android API | 21+ (Android 5.0 Lollipop) | | Compile SDK | 34+ | | Java | 8+ (JVM target 1.8) | | Kotlin | 1.6+ (if using Kotlin) | You'll also need your **Workspace ID** and **API Key** from your Permutive dashboard. ## Latest Versions | Package | Version | | ---------- | ------- | | Core | 1.12.0 | | Google Ads | 2.2.0 | | AppNexus | 1.7.0 | For API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ## Installation Ensure you have Maven Central in your project's `settings.gradle.kts`: ```kotlin theme={"dark"} dependencyResolutionManagement { repositories { google() mavenCentral() } } ``` Add the Permutive SDK to your app module's `build.gradle.kts` or `build.gradle`: ```kotlin build.gradle.kts theme={"dark"} dependencies { // Core SDK (required) implementation("com.permutive.android:core:1.12.0") // Optional add-ons implementation("com.permutive.android:google-ads:2.2.0") // Google Ad Manager implementation("com.permutive.android:appnexus:1.7.0") // Xandr / AppNexus } ``` ```groovy build.gradle theme={"dark"} dependencies { // Core SDK (required) implementation "com.permutive.android:core:1.12.0" // Optional add-ons implementation "com.permutive.android:google-ads:2.2.0" // Google Ad Manager implementation "com.permutive.android:appnexus:1.7.0" // Xandr / AppNexus } ``` Sync your project with Gradle files to download the dependencies. ## Optional Add-Ons The Google Ads add-on provides: * Automatic AAID (Android Advertising ID) identification * Helper methods for Google Ad Manager targeting * Automatic contextual cohort integration (v2.2.0+) ```kotlin theme={"dark"} implementation("com.permutive.android:google-ads:2.2.0") ``` **Requirements:** * Google Play Services Ads dependency (included transitively) * `AD_ID` permission for Android API 31+ Learn how to integrate with Google Ad Manager The AppNexus add-on provides: * Helper methods for Xandr/AppNexus ad targeting * Automatic impression tracking * Automatic contextual cohort integration (v1.7.0+) ```kotlin theme={"dark"} implementation("com.permutive.android:appnexus:1.7.0") ``` **Requirements:** * Xandr SDK dependency (must be added separately) Learn how to integrate with Xandr/AppNexus ## Version Compatibility ### Android API Levels | SDK Version | Minimum Android API | Target Android API | | --------------- | ------------------- | ------------------ | | 1.11.x | 21 (Android 5.0) | 34 (Android 14) | | 1.10.x | 21 (Android 5.0) | 34 (Android 14) | | 1.8.0 - 1.9.x | 21 (Android 5.0) | 34 (Android 14) | | 1.7.x and below | 16 (Android 4.1) | 33 (Android 13) | ### Add-On Compatibility | Add-On | Minimum Core Version | Notes | | ---------------- | -------------------- | ----------------------------------- | | google-ads 2.2.0 | 1.10.0 | Contextual cohorts support | | google-ads 2.1.0 | 1.8.0 | Minimum API 23 required | | appnexus 1.7.0 | 1.10.0 | Contextual cohorts support | | appnexus 1.6.x | 1.8.0+ | Compatible with older core versions | ## ProGuard / R8 If you're using code minification, the SDK includes consumer ProGuard rules automatically. No additional configuration is required. ## Troubleshooting **Cause:** Maven Central repository not configured. **Solution:** Add Maven Central to your `settings.gradle.kts`: ```kotlin theme={"dark"} dependencyResolutionManagement { repositories { google() mavenCentral() } } ``` **Cause:** Multiple SDK versions in dependencies. **Solution:** Force version resolution: ```kotlin theme={"dark"} configurations.all { resolutionStrategy { force("com.permutive.android:core:1.12.0") force("com.permutive.android:google-ads:2.2.0") } } ``` Check dependencies with: `./gradlew app:dependencies` **Cause:** Minification removing SDK classes. **Solution:** The SDK includes consumer ProGuard rules automatically. If issues persist, contact support. ## Next Steps Set up Permutive in your Application class Track your first page view Verify your integration is working Solutions to common issues # Quick Start Guide Source: https://docs.permutive.com/sdks/mobile/android/getting-started/quick-start Get up and running with the Permutive Android SDK in minutes Get up and running with the Permutive Android SDK. This guide will help you install the SDK, initialize it, and track your first page view. **Prerequisites:** * Minimum Android API level 21 (Android 5.0) * Your Permutive **Workspace ID** and **API Key** (available from your Permutive dashboard) * Your project enabled for Android by Permutive (contact your Customer Success Manager if unsure) Add the Permutive SDK to your app's `build.gradle.kts` or `build.gradle` file: ```kotlin build.gradle.kts theme={"dark"} dependencies { implementation("com.permutive.android:core:1.12.0") } ``` ```groovy build.gradle theme={"dark"} dependencies { implementation "com.permutive.android:core:1.12.0" } ``` Sync your project with Gradle files. Initialize Permutive in your `Application` class. The Permutive object should be created **once** as a singleton. ```kotlin Kotlin theme={"dark"} import android.app.Application import com.permutive.android.Permutive import java.util.UUID class MyApplication : Application() { // Create a single instance of Permutive using lazy initialization val permutive by lazy { Permutive( context = this, workspaceId = UUID.fromString("YOUR_WORKSPACE_ID"), apiKey = UUID.fromString("YOUR_API_KEY") ) } override fun onCreate() { super.onCreate() // The SDK will initialize when first accessed } } ``` ```java Java theme={"dark"} import android.app.Application; import com.permutive.android.Permutive; import java.util.UUID; public class MyApplication extends Application { private Permutive permutive; // Create a single instance of Permutive using double-checked locking public Permutive getPermutive() { if (permutive == null) { synchronized (this) { if (permutive == null) { permutive = new Permutive.Builder() .context(this) .workspaceId(UUID.fromString("YOUR_WORKSPACE_ID")) .apiKey(UUID.fromString("YOUR_API_KEY")) .build(); } } } return permutive; } } ``` Create only **one** instance of the Permutive object. Creating multiple instances will result in undefined behavior. Track a page view from an Activity using `PageTracker`. **PageTracker is the recommended approach** as it integrates with Permutive's standard events and enables richer insights. ```kotlin Kotlin theme={"dark"} import androidx.appcompat.app.AppCompatActivity import android.net.Uri import android.os.Bundle import com.permutive.android.EventProperties import com.permutive.android.PageTracker class MainActivity : AppCompatActivity() { private val permutive by lazy { (application as MyApplication).permutive } private lateinit var pageTracker: PageTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Track a page view with PageTracker trackMainScreen() } private fun trackMainScreen() { pageTracker = permutive.trackPage( title = "Home Screen", url = Uri.parse("app://main"), eventProperties = EventProperties.from( "screen_name" to "MainActivity", "session_start" to true ) ) } override fun onPause() { super.onPause() // Pause tracking when screen is not visible pageTracker.pause() } override fun onResume() { super.onResume() // Resume tracking when screen is visible pageTracker.resume() } override fun onDestroy() { super.onDestroy() // Always close the tracker when done pageTracker.close() } } ``` ```java Java theme={"dark"} import androidx.appcompat.app.AppCompatActivity; import android.net.Uri; import android.os.Bundle; import com.permutive.android.EventProperties; import com.permutive.android.PageTracker; import com.permutive.android.Permutive; public class MainActivity extends AppCompatActivity { private Permutive permutive; private PageTracker pageTracker; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); permutive = ((MyApplication) getApplication()).getPermutive(); // Track a page view with PageTracker trackMainScreen(); } private void trackMainScreen() { EventProperties properties = new EventProperties.Builder() .with("screen_name", "MainActivity") .with("session_start", true) .build(); pageTracker = permutive.trackPage( properties, "Home Screen", Uri.parse("app://main"), null // referrer ); } @Override protected void onPause() { super.onPause(); // Pause tracking when screen is not visible pageTracker.pause(); } @Override protected void onResume() { super.onResume(); // Resume tracking when screen is visible pageTracker.resume(); } @Override protected void onDestroy() { super.onDestroy(); // Always close the tracker when done pageTracker.close(); } } ``` **Why PageTracker?** PageTracker automatically tracks Pageview events with proper structure, measures engagement time and scroll depth, integrates seamlessly with Permutive's insights platform, enables contextual cohorts when URLs are provided, and associates related events with the page context. Enable debug logging to verify events are being tracked: ```kotlin theme={"dark"} override fun onCreate() { super.onCreate() permutive.setDeveloperMode(true) } ``` ```bash theme={"dark"} adb shell setprop log.tag.Permutive VERBOSE adb logcat -s Permutive ``` **What to look for in logs:** ``` D/Permutive: Starting Permutive v1.12.0 D/Permutive: Fetched configuration information D/Permutive: Page started (id: ): title: Home Screen url: app://main D/Permutive: Published events with names (Pageview) (Accepted: 1 / 1) ``` If you see "Accepted: 1 / 1" and the Pageview event, your integration is working! ## Next Steps Learn how to track user engagement with content Connect user behavior across sessions and devices Integrate with GAM for personalized advertising Integrate with Xandr ad platform For video streaming or CTV applications Comprehensive verification and troubleshooting ## Troubleshooting **Cause:** Invalid credentials or Android not enabled for your workspace. **Solution:** 1. Verify your Workspace ID and API Key are correct 2. Ensure you're using `workspaceId` (not the deprecated `projectId`) 3. Contact your Customer Success Manager to verify Android is enabled **Cause:** Event schema doesn't match what's configured in your Permutive dashboard. **Solution:** 1. Ensure the event name matches exactly (case-sensitive) 2. Verify property names and types match your schema 3. Check logs for detailed validation errors **Cause:** Debug logging not enabled. **Solution:** Enable developer mode or use ADB commands shown in Step 4. See the complete troubleshooting guide for solutions to more issues # Verifying Your Integration Source: https://docs.permutive.com/sdks/mobile/android/getting-started/verification Verify your Permutive Android SDK integration is working correctly This guide shows you how to verify your Permutive Android SDK integration is working correctly by checking debug logs. **Prerequisites:** * SDK installed and initialized * **adb** (Android Debug Bridge) installed on your computer * Device configured for developer mode ## Enable Debug Logging Debug logging is disabled by default. Enable it using one of these methods: Enable debug logging via command line: ```bash theme={"dark"} # Enable verbose logging adb shell setprop log.tag.Permutive VERBOSE # Start capturing logs adb logcat -s Permutive ``` To disable later: ```bash theme={"dark"} adb shell setprop log.tag.Permutive INFO ``` Enable developer mode programmatically: ```kotlin Kotlin theme={"dark"} // In debug builds only if (BuildConfig.DEBUG) { permutive.setDeveloperMode(true) } ``` ```java Java theme={"dark"} // In debug builds only if (BuildConfig.DEBUG) { permutive.setDeveloperMode(true); } ``` Use `BuildConfig.DEBUG` to ensure developer mode is only enabled in debug builds, never in production. ## What to Verify When the SDK starts successfully, you should see: ``` D/Permutive(15399): Starting Permutive v1.12.0 D/Permutive(15399): Fetched configuration information ``` This confirms SDK initialized successfully and credentials are correct. **If you see an error:** ``` D/Permutive(15124): Error fetching configuration - please check that your workspace id & API key is correct ``` Check your Workspace ID, API Key, and ensure Android is enabled for your workspace. When identity is set, you should see: ``` D/Permutive(15859): Identified user with aliases: aaid, default ``` Common aliases: * **aaid** - Android Advertising ID (if using AaidAliasProvider) * **default** - Default anonymous ID * **user\_id** - Custom user ID * **email\_sha256** - Hashed email When events are tracked and accepted: ``` D/Permutive(15859): Published events with names (Pageview, SegmentEntry) (Accepted: 4 / 4) ``` All events accepted = Your integration is working correctly! **If events are rejected**, you'll see schema validation errors with details about what needs to be fixed. When ads request targeting data: ``` D/Permutive: Permutive segments appended to Google Ad request: seg_123, seg_456, seg_789 ``` This confirms cohort IDs are being added to ad requests. ## PageTracker Lifecycle If you're using the PageTracker API, verify this sequence in logs: ``` Page started (id: abc123): title: Article Title url: https://example.com/article referrer: https://example.com/home properties: {article_id=12345, category=technology} ``` Logged when `pageTracker = permutive.trackPage(...)` is called. ``` Page paused (id: abc123) ``` Logged when `pageTracker.pause()` is called (typically in `onPause()`). ``` Page resumed (id: abc123) ``` Logged when `pageTracker.resume()` is called (typically in `onResume()`). ``` Page stopped (id: abc123) ``` Logged when `pageTracker.close()` is called (typically in `onDestroy()`). ``` Page percentage viewed updated (id: abc123) to 75% ``` Logged when `pageTracker.updatePercentageViewed()` is called. ## Schema Validation Errors If events are rejected due to schema violations: ``` D/Permutive(16644): Error publishing event with name "Pageview": D/Permutive(16644): Code: 1007 D/Permutive(16644): Status: BadRequest D/Permutive(16644): Cause: Schema validation failed with reason(s): [#: extraneous key [publishingDate] is not permitted] [#/article/categories: expected type: JSONArray, found: String] ``` **How to fix:** 1. **Unknown property** - Remove property or add it to your schema in the dashboard 2. **Type mismatch** - Fix the property type in your code: ```kotlin theme={"dark"} // Wrong - String instead of Array EventProperties.from("categories" to "Technology") // Correct - Array type EventProperties.from("categories" to listOf("Technology", "Mobile")) ``` Events with schema violations are **rejected by servers** and will not be processed. Always fix schema issues before releasing your app. ## Common Verification Issues **Solutions:** 1. Verify logging is enabled: `adb shell setprop log.tag.Permutive VERBOSE` 2. Check adb is connected: `adb devices` 3. Restart logcat: `adb logcat -c` then `adb logcat -s Permutive` 4. Verify SDK is initialized **Causes:** 1. Dashboard requires time to process events (5-10 minutes) 2. Event filtering in dashboard 3. Date/time range in dashboard **Solutions:** 1. Wait 10 minutes and refresh dashboard 2. Check dashboard filters 3. Verify date/time range includes now **Causes:** 1. Clearing app data between sessions 2. Not setting identity on initialization 3. Using test/emulator that resets **Solutions:** 1. Don't clear app data during testing 2. Set identity or use AAID provider at initialization 3. Test on physical device ## Verification Checklist Use this checklist to verify your integration: ### Basic Setup * [ ] SDK starts successfully ("Starting Permutive v1.12.0") * [ ] Configuration fetched without errors * [ ] Workspace ID and API Key are correct ### Identity * [ ] Identity log appears on first launch * [ ] Correct aliases are shown * [ ] Identity persists across app restarts ### Event Tracking * [ ] Events are being published * [ ] All events show "Accepted" (not rejected) * [ ] No schema validation errors * [ ] Correct event names (case-sensitive) ### PageTracker (if using) * [ ] "Page started" log appears * [ ] "Page paused" when activity pauses * [ ] "Page resumed" when activity resumes * [ ] "Page stopped" when activity destroyed ### Ad Targeting (if using) * [ ] Segments appended to ad requests * [ ] Targeting log appears when ads load ### Dashboard * [ ] Events appearing in dashboard (may take a few minutes) * [ ] User cohorts showing (after qualifying events) ## Next Steps Once verification is complete: 1. Remove debug logging from production builds 2. Test all user flows that include tracking 3. Verify dashboard data after 24 hours of live usage 4. Monitor for errors in production logs Learn about PageTracker lifecycle Property types and validation User identification Solutions to common issues # Migration Guide: v1.12.x Source: https://docs.permutive.com/sdks/mobile/android/guides/migration/v1-12 Upgrade to Permutive Android SDK v1.12.x and opt into config-driven automatic ID collection This guide covers upgrading to Permutive Android SDK v1.12.x, which introduces **config-driven automatic ID collection**. When enabled for your workspace, the SDK automatically collects the user's Android Advertising ID (AAID) and IP address as identity aliases — with no provider code required. **Migration Difficulty:** Easy | **Estimated Time:** 15 minutes | **Breaking Changes:** None ## What's New in v1.12.0 The SDK captures the AAID as an `aaid` alias when enabled in your workspace config — no `AaidAliasProvider` needed The SDK captures the user's IP as an `ip_address` alias from an internal endpoint — no app changes required **Good news:** This release is fully backward compatible with no breaking changes or deprecations. Automatic collection is **off by default** and is enabled remotely through your dashboard. ## How Automatic ID Collection Works Collection is driven by your workspace configuration, not by app code. Once you enable it for your workspace in the dashboard, the SDK picks it up on its next config refresh. * Stored as an alias with tag **`aaid`**, the priority defined in your config, and no expiry. * **Re-fetched on each new session** to detect Limit Ad Tracking changes, AAID resets, and priority changes from the server config. * If the user has **Limit Ad Tracking** enabled, no alias is stored and any existing `aaid` alias is cleared. * If an alias with the same tag, value, and priority already exists (from a previous auto-collection **or** a manual [`AaidAliasProvider`](/sdks/mobile/android/integrations/aaid-provider)), storage is skipped to avoid duplicates. * Stored as an alias with tag **`ip_address`**, the priority defined in your config, and no expiry. * Retrieved from Permutive's internal endpoint and updated when the IP changes. * **No app or manifest changes are required** for IP collection. ## Standard Upgrade Upgrading the SDK requires only a dependency bump. Update your `build.gradle.kts` or `build.gradle` to the v1.12.x core: ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.11.3") } ``` ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.12.0") } ``` Then sync and rebuild: ```bash theme={"dark"} ./gradlew clean build ``` Add-on libraries (`google-ads`, `appnexus`) are unaffected by this release. Automatic collection stays **off** until you enable it for your workspace in the dashboard, so no further changes are needed to complete the upgrade. ## Opting Into AAID Collection The steps below are **only required if you opt into automatic AAID collection**. They do not apply to a standard version upgrade, and they are not needed for automatic IP address collection (which requires no app or manifest changes). To collect the AAID, the client app must declare the `AD_ID` permission in its `AndroidManifest.xml`: ```xml theme={"dark"} ``` This permission is required on **Android 13 (API 33)** and above. Without it, the AAID is returned as all zeros (`00000000-0000-0000-0000-000000000000`), and the SDK treats this the same as no AAID — nothing is stored. Google Play Services must also be available on the device. If Play Services is missing or unavailable, the fetch fails silently and no alias is stored. Because the AAID is now collected and sent off-device, declare it in **Play Console → App content → Data safety**: * **Data type collected:** `Device or other IDs` → `Advertising ID` (under `Personal info`) * **Collection:** Yes, collected; sent off-device * **Optional vs. required:** Optional — the user can deny via Limit Ad Tracking or by resetting the AAID, and the SDK respects both * **Purposes:** whichever apply to your use of Permutive (typically Analytics, Advertising or marketing, Personalization) Keep your Data Safety declaration in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to Play Store policy violations. Automatic collection is enabled remotely via the dashboard. Contact your Customer Success Manager to help enabling or disabling the feature. ## Verifying Collection Enable developer logging and look for the identity being set: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) ``` ``` D/Permutive: Identified user with aliases: aaid, ip_address ``` See the [Verification Guide](/sdks/mobile/android/getting-started/verification) for complete steps. ## Manual vs. Automatic AAID Collection If you already add [`AaidAliasProvider`](/sdks/mobile/android/integrations/aaid-provider) manually, we recommend **removing the manual provider** once automatic collection is enabled, unless you have a specific use case for it. Automatic, config-driven collection covers the same capture, lets you enable or disable it without shipping an app update, and is managed centrally from the dashboard. Running both is safe in the meantime — automatic collection deduplicates against any existing `aaid` alias with the same value and priority, so you won't get duplicate identities during the transition. | | Manual (`AaidAliasProvider`) | Automatic (config-driven) | | ----------------------------- | ---------------------------- | ------------------------- | | Enablement | App code at initialization | Workspace config (remote) | | App update needed to toggle | Yes | No | | `AD_ID` permission required | Yes (Android 13+) | Yes (Android 13+) | | Google Play Services required | Yes | Yes | | Alias tag | `aaid` | `aaid` | ## Rollback If you need to roll back to v1.11.x: ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.11.3") } ``` Then sync and rebuild. You can leave the `AD_ID` permission in your manifest — it is harmless when collection is disabled. ## Requirements v1.12.0 maintains the same minimum requirements as v1.11.x: | Requirement | Version | | ----------- | ---------------------- | | Android API | 21+ (Android 5.0) | | Compile SDK | 34+ | | Kotlin | 1.6+ (if using Kotlin) | | Java | 8+ (JVM target 1.8) | ## Getting Help Manual AAID capture and privacy considerations How aliases and identities work Verify identity capture Solutions to common issues # Migration Guide: v1.9.x to v1.10.x Source: https://docs.permutive.com/sdks/mobile/android/guides/migration/v1-9-to-v1-10 Upgrade from Permutive Android SDK v1.9.x to v1.10.x This guide covers migrating from Permutive Android SDK v1.9.x to v1.10.x, which introduces contextual cohorts, Dagger dependency injection, and several improvements. **Migration Difficulty:** Very Easy | **Estimated Time:** 15 minutes | **Breaking Changes:** None ## What's New in v1.10.0 Content-based segmentation for real-time targeting Internal dependency injection framework (v2.53.1) Automatic contextual cohort targeting for GAM Automatic contextual cohort targeting for Xandr **Good news:** This release is fully backward compatible with no breaking changes or deprecations. ## Migration Steps Update your `build.gradle.kts` or `build.gradle`: ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.9.8") implementation("com.permutive.android:google-ads:2.1.0") implementation("com.permutive.android:appnexus:1.6.1") } ``` ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.10.0") implementation("com.permutive.android:google-ads:2.2.0") // For GAM contextual implementation("com.permutive.android:appnexus:1.7.0") // For Xandr contextual } ``` ```bash theme={"dark"} ./gradlew clean build ``` Your existing code will continue to work without changes. Test to ensure: * Events are still being tracked * Cohorts are being received * Ad targeting is working ## Using New Features ### Contextual Cohorts Contextual cohorts are automatically enabled if your workspace has the feature activated. No code changes required! ```kotlin theme={"dark"} val activations = permutive.currentActivations // Get Google Ad Manager contextual cohorts val gamContextual = activations["dfp_contextual"].orEmpty() // Get Xandr contextual cohorts val xandrContextual = activations["appnexus_adserver_contextual"].orEmpty() ``` If you're using our add-on libraries, contextual cohorts are automatically included: **Google Ad Manager:** ```kotlin theme={"dark"} // Contextual cohorts automatically added with key "prmtvctx" val adRequest = AdManagerAdRequest.Builder() .addPermutiveTargeting(permutive) .build() ``` **Xandr/AppNexus:** ```kotlin theme={"dark"} // Contextual cohorts automatically added adView.addPermutiveTargeting(permutive) ``` See the [Contextual Data Guide](/sdks/mobile/android/core-concepts/contextual-data) for full documentation. ### Dagger Integration v1.10.0 introduces Dagger for internal dependency management. This is an internal implementation detail. **No action required.** Dagger is used internally by the SDK and doesn't require any changes to your code. If your app also uses Dagger and you experience conflicts: 1. Check your Dagger version matches or is compatible with v2.53.1 2. Don't exclude Dagger from the Permutive SDK dependencies: ```kotlin theme={"dark"} // Don't do this: implementation("com.permutive.android:core:1.10.0") { exclude(group = "com.google.dagger") // Will cause issues! } ``` ## Testing Your Migration Enable debug logging and verify events are still being tracked: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) ``` Look for: ``` D/Permutive: Published events with names (Pageview) (Accepted: 1 / 1) ``` Verify behavioral cohorts are still working: ```kotlin theme={"dark"} val cohorts = permutive.currentCohorts Log.d("Migration Test", "Cohorts: ${cohorts.size}") ``` If contextual is enabled for your workspace: ```kotlin theme={"dark"} // Track a page with URL val pageTracker = permutive.trackPage( title = "Test Article", url = Uri.parse("https://example.com/test") ) // Wait a moment for classification Handler(Looper.getMainLooper()).postDelayed({ val contextual = permutive.currentActivations["dfp_contextual"] Log.d("Migration Test", "Contextual cohorts: $contextual") }, 2000) ``` Verify ads are still loading with targeting: ```kotlin theme={"dark"} val adRequest = AdManagerAdRequest.Builder() .addPermutiveTargeting(permutive) .build() adView.loadAd(adRequest) // Check logs for: // D/Permutive: Permutive segments appended to Google Ad request: ... ``` ## Rollback If you need to rollback to v1.9.x: ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.9.8") implementation("com.permutive.android:google-ads:2.1.0") implementation("com.permutive.android:appnexus:1.6.1") } ``` Then sync and rebuild. ## Requirements v1.10.0 maintains the same minimum requirements as v1.9.x: | Requirement | Version | | ----------- | ---------------------- | | Android API | 21+ (Android 5.0) | | Compile SDK | 34+ | | Kotlin | 1.6+ (if using Kotlin) | | Java | 8+ (JVM target 1.8) | ## Getting Help Solutions to common issues Full contextual documentation GAM integration guide Understanding segments # AAID Provider Source: https://docs.permutive.com/sdks/mobile/android/integrations/aaid-provider Automatically identify users by Android Advertising ID The AAID (Android Advertising ID) provider automatically identifies users by their Android Advertising ID. This is available through the Google Ads add-on library. ## Overview The `AaidAliasProvider` provides: * **Automatic AAID capture** - No manual ID retrieval needed * **Persistent identification** - User tracking across app sessions * **Privacy compliant** - Respects user opt-out preferences * **Zero maintenance** - Automatically updates when AAID changes ## Prerequisites 1. **Google Ads add-on** installed 2. **Google Play Services** on device 3. **AD\_ID permission** (Android API 33+) *** ## Installation The AAID provider is included in the Google Ads add-on: ```kotlin theme={"dark"} dependencies { implementation("com.permutive.android:core:1.12.0") implementation("com.permutive.android:google-ads:2.2.0") // Includes AaidAliasProvider } ``` See [Installation Guide](/sdks/mobile/android/getting-started/installation) for details. *** ## Basic Setup ### Add AaidAliasProvider at Initialization Add the `AaidAliasProvider` when creating your Permutive instance: ```kotlin Kotlin theme={"dark"} import android.app.Application import com.permutive.android.Permutive import com.permutive.android.aaid.AaidAliasProvider class MyApplication : Application() { val permutive by lazy { Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, aliasProviders = listOf(AaidAliasProvider(this)) // Add AAID provider ) } } ``` ```java Java theme={"dark"} import android.app.Application; import com.permutive.android.Permutive; import com.permutive.android.aaid.AaidAliasProvider; public class MyApplication extends Application { private Permutive permutive; public Permutive getPermutive() { if (permutive == null) { synchronized (this) { if (permutive == null) { permutive = new Permutive.Builder() .context(this) .workspaceId(YOUR_WORKSPACE_ID) .apiKey(YOUR_API_KEY) .aliasProvider(new AaidAliasProvider(this)) // Add AAID provider .build(); } } } return permutive; } } ``` That's it! The AAID will now be automatically captured and set as a user identity. *** ## Required Permissions (Android API 33+) ### Add AD\_ID Permission From Android 13 (API 33) and later, the `AD_ID` permission is required to access the AAID. Add this to your `AndroidManifest.xml`: ```xml theme={"dark"}

...

``` **Important for Android 13+** Without the `AD_ID` permission on Android API 33+, the AAID is returned as all zeros (`00000000-0000-0000-0000-000000000000`) and the `AaidAliasProvider` will not capture it. ### Checking Permission Status The permission is automatically granted - no runtime permission request needed. However, users can opt out of ad tracking in their device settings. *** ## How It Works ### Automatic ID Capture When `AaidAliasProvider` is added: 1. **On initialization** - AAID is retrieved from Google Play Services 2. **Async retrieval** - ID fetched in background (non-blocking) 3. **Auto-set identity** - AAID automatically set as user alias 4. **Tag created** - Stored with tag `"aaid"` 5. **Persisted** - AAID saved for future sessions ### Alias Details The AAID is stored as an alias with: * **Tag:** `"aaid"` * **Identity:** The advertising ID (e.g., `"38400000-8cf0-11bd-b23e-10b96e40000d"`) * **Priority:** 0 (default) * **Expiry:** Never (unless manually cleared) ### User Opt-Out Handling If a user opts out of ad personalization in device settings: * The AAID provider will receive a zeroed-out ID * This zeroed-out ID will not be set as an alias * Permutive will use the default anonymous ID instead *** ## Combining with Other Identities You can use AAID alongside other identity methods: ### AAID + Custom Identity ```kotlin theme={"dark"} val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, identity = "user_12345", // Your internal user ID aliasProviders = listOf(AaidAliasProvider(this)) // + AAID ) ``` Now the user has two identities: 1. Custom identity: `"user_12345"` (tag: `"user_id"`) 2. AAID: `"38400000-8cf0-11bd-b23e-10b96e40000d"` (tag: `"aaid"`) ### AAID + Multiple Custom Aliases ```kotlin theme={"dark"} import com.permutive.android.Alias val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, customAliases = listOf( Alias.create( tag = "email_sha256", identity = hashSHA256(userEmail), priority = 0 ), Alias.create( tag = "internal_id", identity = "user_12345", priority = 1 ) ), aliasProviders = listOf(AaidAliasProvider(this)) // + AAID ) ``` See [Identity Management](/sdks/mobile/android/core-concepts/identity-management) for more on multiple identities. *** ## Verification ### Verify AAID is Set Enable debug logging to verify AAID is captured: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) ``` Look for logs like: ``` D/Permutive: Setting identity with tag: aaid, value: 38400000-8cf0-11bd-b23e-10b96e40000d ``` ### Check Current Identities You can programmatically check if AAID is set: ```kotlin theme={"dark"} // This is internal API - use debug logs instead // But for verification in tests: // Check that events include AAID in aliases ``` See [Verification Guide](/sdks/mobile/android/getting-started/verification) for complete verification steps. *** ## Use Cases ### Anonymous User Tracking For apps without user login, AAID provides persistent tracking: ```kotlin theme={"dark"} // No custom identity - just AAID val permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, aliasProviders = listOf(AaidAliasProvider(this)) ) ``` User is identified by AAID across app launches and sessions. ### Logged-In User + AAID For apps with user accounts, combine both: ```kotlin theme={"dark"} class MyApplication : Application() { val permutive by lazy { Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, aliasProviders = listOf(AaidAliasProvider(this)) ) } fun onUserLoggedIn(userId: String) { // Add user ID as additional identity permutive.setIdentity( tag = "internal_user_id", identity = userId ) } fun onUserLoggedOut() { // AAID remains, but remove user ID // (User is still tracked via AAID) } } ``` ### Cross-Device Tracking AAID is device-specific. For cross-device tracking, combine with email or other identifiers: ```kotlin theme={"dark"} fun onUserLoggedIn(email: String) { permutive.setIdentity( tag = "email_sha256", identity = hashSHA256(email) ) // Now user has both AAID (device) and email hash (cross-device) } ``` *** ## Privacy Considerations ### GDPR Compliance AAID is considered personal data under GDPR. Ensure: * ✅ User consent obtained before initialization * ✅ Privacy policy explains AAID usage * ✅ User can opt out via device settings * ✅ Data can be deleted on request ```kotlin theme={"dark"} class MyApplication : Application() { private var _permutive: Permutive? = null val permutive: Permutive? get() = _permutive fun onConsentGranted() { if (_permutive == null) { _permutive = Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY, aliasProviders = listOf(AaidAliasProvider(this)) // Only after consent ) } } } ``` Contact your Customer Success Manager for details on GDPR compliance. ### User Opt-Out Users can opt out of ad personalization in: * **Settings → Google → Ads → Opt out of Ads Personalization** When opted out: * AAID is zeroed out (`00000000-0000-0000-0000-000000000000`) * `AaidAliasProvider` will not set this as an identity * Permutive uses anonymous ID instead ### Data Deletion To clear all user data including AAID: ```kotlin theme={"dark"} permutive.clearPersistentData() ``` This removes: * All identities (including AAID) * All event data * All cohort information See [Identity Management](../core-concepts/identity-management.mdx#removing-persistent-data). *** ## Troubleshooting **Problem:** AAID not appearing in events. **Causes:** 1. Google Ads add-on not installed 2. `AaidAliasProvider` not added to Permutive 3. Missing `AD_ID` permission (Android 13+) 4. Google Play Services not available 5. User opted out of ad personalization **Solutions:** 1. Verify `google-ads:2.2.0` is in dependencies 2. Add `AaidAliasProvider` to `aliasProviders` list 3. Add `AD_ID` permission to manifest (Android 13+) 4. Test on device with Google Play Services 5. Check user's ad personalization settings 6. Enable debug logging to see AAID capture attempts **Problem:** Error about AD\_ID permission. **Cause:** `AD_ID` permission not declared. **Solution:** Add to `AndroidManifest.xml`: ```xml theme={"dark"} ``` **Problem:** AAID cannot be retrieved. **Cause:** Device doesn't have Google Play Services (e.g., some devices in China). **Solutions:** 1. Implement fallback identification method 2. Use custom identity instead 3. Check Play Services availability: ```kotlin theme={"dark"} val availability = GoogleApiAvailability.getInstance() val resultCode = availability.isGooglePlayServicesAvailable(context) if (resultCode == ConnectionResult.SUCCESS) { // Play Services available - AAID will work } else { // Play Services not available - use fallback } ``` **Problem:** AAID changes unexpectedly. **Causes:** 1. User reset advertising ID in settings 2. Factory reset 3. App reinstalled **This is expected behavior.** AAID can change, and your implementation should handle this gracefully. See [Common Errors](/sdks/mobile/android/troubleshooting/common-errors) for more troubleshooting. *** ## Best Practices * Add `AaidAliasProvider` at SDK initialization * Declare `AD_ID` permission for Android 13+ * Obtain user consent before capturing AAID (GDPR) * Combine AAID with other identifiers for robustness * Handle Google Play Services unavailability * Respect user opt-out preferences * Use AAID without user consent (GDPR) * Forget `AD_ID` permission on Android 13+ * Rely solely on AAID (can change or be unavailable) * Assume AAID is always available * Ignore user opt-out preferences *** ## Related Documentation Use AAID with GAM Multiple identities SDK setup Verify AAID capture Solve common issues *** ## API Reference For complete API documentation, see the [Javadocs](https://sdk-docs.permutive.com/index.html). ### AaidAliasProvider * `AaidAliasProvider(context: Context)` - Creates AAID alias provider ### Usage in Permutive **Kotlin:** ```kotlin theme={"dark"} Permutive( context = ..., workspaceId = ..., apiKey = ..., aliasProviders = listOf(AaidAliasProvider(context)) ) ``` **Java:** ```java theme={"dark"} new Permutive.Builder() .context(context) .workspaceId(workspaceId) .apiKey(apiKey) .aliasProvider(new AaidAliasProvider(context)) .build() ``` *** ## Getting Help If you encounter issues with AAID: 1. Check [Troubleshooting Guide](/sdks/mobile/android/troubleshooting/common-errors) 2. Verify Google Ads add-on is installed 3. Confirm `AD_ID` permission is declared (Android 13+) 4. Enable debug logging 5. Test on device with Google Play Services 6. Contact your Customer Success Manager For Google Play Services issues, consult [Google's documentation](https://developers.google.com/android/guides/overview). # Integrations Source: https://docs.permutive.com/sdks/mobile/android/integrations/overview Connect the Android SDK with ad platforms and tracking providers The Permutive Android SDK integrates with major ad platforms to enable audience targeting. For detailed setup instructions, see the main integration documentation for each platform. ## Ad Server Integrations Set up GAM targeting for Android apps Configure Xandr ad platform targeting ## SDK Providers Automatic Android advertising ID tracking # Android SDK Source: https://docs.permutive.com/sdks/mobile/android/overview Integrate Permutive into your Android application for user segmentation, personalization, and ad targeting ## Overview The Permutive Android SDK enables user segmentation, personalization, and ad targeting in your Android application. Track user behavior, manage identities across devices, and deliver targeted advertising through integrations with major ad platforms. ## Getting Started New to the Permutive Android SDK? Start here. Get up and running with your first page view in minutes Detailed installation and dependency setup SDK initialization patterns and configuration Verify your integration is working correctly ## Core Concepts Understand the fundamental concepts of the Permutive SDK. Track users across devices and sessions Structure and validate event data Understanding user segmentation Content-based real-time targeting ## Features Detailed guides for specific SDK features. Track pageviews and user engagement (recommended approach) Track custom events Track video content viewing Track video advertisement engagement React to cohort changes in real-time ## Integrations Connect Permutive with ad platforms and other services. Google Ad Manager, Xandr, and more Automatic advertising ID tracking ## Common Tasks **PageTracker is the recommended approach** for tracking user interactions as it integrates with Permutive's standard events and provides richer insights. ```kotlin theme={"dark"} class ArticleActivity : AppCompatActivity() { private lateinit var pageTracker: PageTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) pageTracker = permutive.trackPage( title = "Article Title", url = Uri.parse("https://example.com/article"), eventProperties = EventProperties.from( "category" to "sports", "author" to "John Doe" ) ) } override fun onPause() { super.onPause() pageTracker.pause() } override fun onResume() { super.onResume() pageTracker.resume() } override fun onDestroy() { super.onDestroy() pageTracker.close() } } ``` ```kotlin theme={"dark"} val emailHash = hashEmail(userEmail) permutive.setIdentity( listOf( Alias.create("email_sha256", emailHash, priority = 0), Alias.create("internal_id", userId, priority = 1) ) ) ``` ```kotlin theme={"dark"} val trigger = triggersProvider.triggerAction("premium_user") { isInCohort -> if (isInCohort) { showPremiumFeatures() } } // Don't forget to close! override fun onDestroy() { super.onDestroy() trigger.close() } ``` ```kotlin theme={"dark"} val adRequest = AdManagerAdRequest.Builder() .addPermutiveTargeting(permutive) .build() adView.loadAd(adRequest) ``` ## Requirements | Requirement | Version | | ----------- | -------------------------- | | Android API | 21+ (Android 5.0 Lollipop) | | Compile SDK | 34+ | | Java | 8+ (JVM target 1.8) | | Kotlin | 1.6+ (if using Kotlin) | ```kotlin theme={"dark"} dependencies { // Core SDK (required) implementation("com.permutive.android:core:1.12.0") // Optional add-ons implementation("com.permutive.android:google-ads:2.2.0") implementation("com.permutive.android:appnexus:1.7.0") } ``` ## Key Concepts ## Additional Resources Best practices, patterns, and how-tos. * **[Migration: v1.9.x to v1.10.x](/sdks/mobile/android/guides/migration/v1-9-to-v1-10)** - Upgrade to the latest version **Coming Soon:** Architecture Patterns, Testing Strategies, GDPR Compliance, and Performance Optimization guides are being developed. API documentation and technical reference. * **[Javadocs](https://sdk-docs.permutive.com/)** - Complete API documentation * **[Sample Apps](https://github.com/permutive/android-sdk-samples)** - Example integrations **Coming Soon:** Changelog, Minimum Versions, and Event Schema reference documentation. ## FAQ **PageTracker** is the recommended approach for most use cases. It automatically tracks Pageview events, measures engagement time and scroll depth, and enables contextual cohorts when URLs are provided. **EventTracker** is for specialized cases where you need to track custom events that don't fit the page model. Enable developer mode in your code: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) ``` Or via ADB: ```bash theme={"dark"} adb shell setprop log.tag.Permutive VERBOSE adb logcat -s Permutive ``` Use hashed emails (SHA-256), internal user IDs, or mobile advertising IDs. Never send plain text PII. See the [Identity Management](/sdks/mobile/android/core-concepts/identity-management) guide for details. Events typically appear within 5 minutes. If you see "Accepted: 1 / 1" in your debug logs, the event was successfully sent. ## Getting Help * **[Troubleshooting Guide](/sdks/mobile/android/troubleshooting/common-errors)** - Solutions to common issues * **Customer Success Manager (CSM)** - For enabling features and exploring use cases * **[Technical Services](mailto:technical-services@permutive.com)** - For technical setup and configuration * **[Support](mailto:support@permutive.com)** - For troubleshooting and help ## Privacy & Compliance Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage. # Release Notes Source: https://docs.permutive.com/sdks/mobile/android/release-notes/index Android SDK updates and announcements * Config-driven automatic ID collection **(New)** * Header encoding for OkHttp 4.x compatibility **(Fix)** * Add 16KB page size support for Android 15+ devices **(Fix)** * Fix missing `logs()` method in Logger interface **(Fix)** * Integrate contextual cohorts with classification models **(Update)** * Integrate content-based contextual cohorts **(New)** * Introduce Dagger as dependency injection framework (v2.53.1) **(New)** * Automatic contextual cohort targeting integration for Google Ad Manager requests **(New)** * Automatic contextual cohort targeting integration for AppNexus/Xandr ad requests **(New)** * Fix issue causing cohort transition event aggregation to stop working in some situations. **(Fix)** * Remove aho-corasick string-searching from cohort processing to reduce memory usage. **(Fix)** * Integrate with new API for audience matching to improve matching based on external data **(New)** * Fix close button on debug overlay **(Fix)** * Fix logging when setting completion percentage **(Fix)** * Update Google Play Services Ads dependency to 24.0.0 **(Update)** * Changed Android minSdk version to 23 **(Update)** * Add aggregations of cohort transition events to PageviewComplete event properties to reduce our network load **(New)** * Fix missing class issues by removing dependency on ktor utils library from the query engine **(Fix)** * Fix issue that could occur when synchronising user state **(Fix)** * Update compile SDK version to 34 **(Update)** * Update Google Play Services Ads dependency to 23.2.0 **(Update)** * Remove `PermutiveAdManagerAdRequestBuilder.addNetworkExtras` function (removed from ads SDK) **(Breaking change)** * Remove `PermutiveAdManagerAdRequestBuilder.setLocation` function (removed from ads SDK) **(Breaking change)** * Deprecate `PermutiveAdManagerAdRequestBuilder.addCustomEventsExtrasBundle` function (deprecated in ads SDK) **(Deprecation)** * Add remotely configurable list of third and second party data providers that are excluded from usage reporting **(New)** * Replace RxJava2 with Kotlin Flow in state synchronisation **(Update)** * Add new feature flag to enable Classification Model cohorts for this version and above **(Update)** * Add video ad tracking functionality through the `AdTracker`. [See here for more information](/sdks/mobile/android/features/video-ad-tracking) **(New)** * Add new container classes for video properties, `MediaTracker.VideoProperties` and `MediaTracker.PageProperties`. **(New)** * Add new `trackVideoView` function which takes the new property objects and deprecate `createVideoTracker`. **(Update)** * Release beta version of the debug overlay UI tool. **(New)** * Add new `TriggersProvider` functions which support `boolean` results for cohorts. **(New)** * Remove Rhino Javascript engine library. **(Update)** * Remove intermediate objects created during event processing to improve memory usage. **(Update)** * Fix RxJava undeliverable exceptions escaping error handling. **(Fix)** * Fix issue resulting from Kotlin reflection library dependency conflicts. **(Fix)** * Update the native query runtime to the latest version with more efficient state updates. This will reduce the number of calls to the Permutive API made by the SDK. **(New)** * Fix crash occurring on devices running Android 25 and below caused by desugared java.time library not being included in AAR. **(Fix)** * Increase minimum Android SDK version from 16 to 21. For more information on why we're doing it and how we'll be minimising disruption [read here](/sdks/mobile/android/guides/migration/v1-9-to-v1-10). * Added support for Classification Model cohorts. **(New)** * Added new properties for retrieving cohorts and activations. `PermutiveSdk.currentCohorts: List` & `PermutiveSdk.currentActivations: Map>`. **(New)** To allow us to support more cohorts we have switched from using integers to strings as cohort IDs. The new properties are equivalent to the old `PermutiveSdk.currentSegments: List` & `PermutiveSdk.currentReactions: Map>` properties respectively. * Deprecate the `PermutiveSdk.currentSegments` & `PermutiveSdk.currentReactions` properties. **(Deprecation)** * Fix a query in the native query runtime. **(Fix)** * Change evaluation of some debug log strings to be lazy. **(Fix)** * Retrieve cohorts using the new `PermutiveSdk.currentActivations` function. **(Update)** * Retrieve cohorts using the new `PermutiveSdk.currentActivations` function. **(Update)** * Downgrade Kotlin requirement to v1.6+. **(Update)** * Enable the native query runtime by default. **(New)** * Fix native query runtime not interpreting some queries correctly. **(Fix)** * Fix issue with external state decoding. **(Fix)** * Fix crash occurring when retrieving Classification Model cohorts **(Fix)** * Fix missing common module classes **(Fix)** * Fix issue with debug event recorder caching large amount of events. **(Fix)** * Remove the "CTV" prefix from the names of our video events tracked through the `MediaTracker` API to better reflect their usecase for all video content. **(Update)** * Update to how we capture the `client.user_agent` event property to allow us to support better device distinction in the insights platform. **(Update)** * Additional fixes to query interpretation when using the native engine. **(Fix)** * Update the new `clearPersistentData` function to always run on coroutine `Dispatchers.IO` to prevent possibility of database access from the wrong thread. **(Fix)** * Added some additional proguard consumer rules to prevent native engine deserialization classes from being removed. **(Fix)** Please ensure you test you application with minification and Permutive debugging enabled (see [verification guide](/sdks/mobile/android/getting-started/verification)) * Fix issue causing certain queries not to be interpreted correctly. **(Fix)** * Add new instance functions for clearing persistent data and deprecate old function. **(New)** The previous `clearPersistentData` function was potentially causing issues with the Permutive SDK database instance resulting in crashes. The new functions are safer to use and also inform of success or failure. * Add migration path for users moving from event-sync to our new native state-sync. **(New)** * Add handling for undelivered exceptions. **(New)** * Fix exception when migrating from database version 4 to 5. **(Fix)** * Add new `setPermutiveAdListener` function which enables automatic impression tracking. For more information see [AppNexus/Xandr integration](/sdks/mobile/android/integrations/appnexus-xandr). **(New)** * Fix issue which caused the SDK to stop if the user received network errors when making an identity call. **(Fix)** * Add new native engine to replace the Rhino Javascript engine. This feature will be rolled out gradually. **(New)** Rhino Javascript will be removed in a subsequent release after rollout of the native engine is complete. * Update EventProperties API so that it allows nullable values. **(New)** * Fix exception which could occur when doing database migration. **(Fix)** * Add support for setting priority and expiry for aliases set through the identity APIs. **(New)** The identity APIs support new functionality for prioritising aliases and deleting them automatically on expiry. For more information see our documentation on [identity management](/sdks/mobile/android/core-concepts/identity-management). * Add support for tracking Fire and Fire TV as platforms. **(New)** Fire and Fire TV devices are now tracked as separate platforms types for clients. * Fix printing of nested EventProperties which previously showed as 'null'. **(Fix)** Nested EventProperties in the developer log were incorrectly showing as null, they now show as the correct nested structure. * Fix memory leak caused by some internal resources not closing correctly. **(Fix)** Parts of the SDK were found to still run even after `close()` was called on an SDK instance. These have now been fixed. * Fix issue that could sometimes cause events to be processed more than once. **(Fix)** Sometimes events could end up being tracked more than once causing slowdown and memory consumption. This has now been fixed. * Update Xandr/AppNexus dependency to 7.X. * Add support for Google Ads slots clicked events. **(New)** Additional information is included in the GAM request which allows for server side generation of slot events. * Fix in-IDE documentation for core APIs. **(New)** API documentation is now accessible in the IDE. * Adds in page engagement support. **(New)** Engagement segments can not be evaluated in the current page, rather than only once that page has closed/completed. * Add video tracking support. **(New)** Similar to pages we now support tracking video events and video engagement using the MediaTracker class. * Fix exception happening when events containing an empty list as a child of `EventProperties` are tracked. **(Fix)** This version has a known issue causing some events not to be tracked. Please use version 1.5.11 * Optimise segmentation engine memory usage. **(New)** An optimised way of passing events to the segmentation engine has been added which will reduce OutOfMemoryErrors. * Fix exception when using `EventProperties` containing a list of `EventProperties`. **(Fix)** Correct property handling has been added for `EventProperties` which contain a value which itself is a list of `EventProperties`. * Add more comprehensive logging to the SDK. **(New)** Improved logging will assist in verifying integrations and debugging any potential issues. See the [verification guide](/sdks/mobile/android/getting-started/verification) for details on what logs are available. * Remove internal logging of current segments and current reactions. **(New)** These can easily be logged externally so have been removed to reduce noise from the internal SDK logs. * Fix memory leaks when restarting the SDK **(Fix)** * Update library dependencies **(New)** Updates Google-Play-Services dependency from v18 to v20. * Update library dependencies **(New)** Updates third party dependencies - room, rxjava, androidx to the latest versions. * Update minimum SDK version to 16 **(New)** Updates minimum SDK version from 14 to 16. * Always identify on startup **(New)** In order to prevent potential identity collapse, the SDK always identifies upon startup, so any such issues can be resolved by the server. * Fix ConcurrentModificationException at startup **(Fix)** The deferred queue has been updated to fix an issue where ConcurrentModificationException can be thrown due to a deferred operation that itself modifies the deferred queue. * Fix SQLite issue when migrating to state sync **(Fix)** Rewrite SQLite query for migration to state sync so that it does not exceed the maximum variable limit for the Android SQLite implementation. * Fix conflicting cache issue with OkHttp **(Fix)** Cache issues can occur if both the host application and the Permutive SDK use OkHttp in the same cache directory. Permutive SDK now uses a subdirectory of the cache directory. * Update URLs to `permutive.app` **(New)** Moving from `permutive.com` - SDK traffic should use `permutive.app` name. * Fine tune metrics for the state-sync/event-sync variants **(Fix)** Metrics are now able to be fine tuned so that the variants do not interfere with the reported data. * Add state synchronisation support **(New)** We now merge off-device state using states rather than raw events. * Fix migration issue with 1.5.2 **(Fix)** Fixes a critical persistence issue when upgrading to 1.5.2 with persisted state from an older version. * Constrain event cache upon startup **(New)** Excess events are dropped upon startup if the events cache is lowered. * Handle OOM exception when evaluating script **(Fix)** We now disable the SDK & report an issue if an OOM condition occured when evaluating the segmentation script. * Update Kotlin to 1.4.20 **(New)** Updated to the latest stable developer release of Kotlin. Upgrading from an older versions of this SDK can result in a migration issue, we strongly recommend using a previous version. If you are using 1.5.2 please contact our support staff for further details. * Disable pre lollipop devices by default **(Fix)** Devices older than 5.0 are unable to communicate with our servers as we use the more secure TLS 1.2 protocol. * Handle OOM exceptions more gracefully **(Fix)** Disable the SDK when an OOM occurs during segmentation, freeing up memory for the host application. * Add CheckResult annotation for all public methods that return values **(New)** Warnings should occur in the IDE when using public functions that returns values. * Updated to Kotlin 1.4.0 **(New)** * Better developer logs & dynamic log support **(New)** It is now possible to dynamically turn on logging for a deployed app, which can help for verification of the deployment. * Fix halting when there is a connection issue **(Fix)** Under some circumstances the SDK would halt execution when a connection issue occurred. * Do not include rejected events in cache **(Fix)** Rejected events are not not included in the events cache. * Fix watson decode issue **(Fix)** Watson would not decode correctly if a client was using a later version of the moshi library. * Add Enterprise workspace support **(New)** Passing through a Workspace Id rather than a Project Id will use segments and events configured for that particular workspace, rather than for the whole organization. If migrating from an existing ProjectId to a new Workspace Id, local state is still retained during the migration. * Stop running the segmentation engine when a memory trim level has been sent by the OS **(New)** When the device starts running out of memory, the Android SDK will shutdown it's running systems until a call to the public APIs is made. * Only track engagement events if configured to **(Fix)** We only send PageviewComplete events if the project is configured for this. * Handle devices that are configured with a DNS sinkhole **(Fix)** Fix issue when a device is connected to a DNS sinkhole under certain conditions the SDK can make repeated requests for the same resource. * Add Watson enrichment support **(New)** EventProperties.ALCHEMY\_\* strings can be used to enrich an event with the watson information provided for the current/page URL. * Add PageviewComplete event **(New)** Adds page engagement support for the Android platform. The PageviewComplete event is automatically generated when calling close on a PageTracker object. * Always use application context on initialisation **(Fix)** Prevents Activity leaks when passing an Activity as the SDK's context, rather than the Application. * Turn off TPD usage reporting as a default **(Fix)** TPD usage reporting is not used by our customers at this time, so this has defaulted to off. * Report SDK version as a metric **(New)** Reporting SDK version will give us better information on current deployments. * Add hashed ip as an event enrichment type **(New)** The string "\$ip\_address\_hash" will now resolve to a hashed version of the client's ip address. * Fix instances of dependencies upon startup **(Fix)** Fixes a potential race condition that could allow double creations of SDK dependencies. * Fix error reporting so that it includes script date/time **(Fix)** To better diagnose issues we now report the query language creation time in error reports. * Handle illegal argument exception when unregistering broadcast receiver **(Fix)** Fixed an issue when unregistering a broadcast receiver that has not yet been registered in some cases. * Always ask server to resolve resources, regardless of cache-control max-age **(Fix)** We now do not honor the cache-control max-age header, as if this is very long we will not fetch the updates files from our servers. * do not generate segment\_exit events for deleted/missing segments **(Fix)** We now do not generate segment\_exit events for missing/deleted segments. * update library dependencies **(New)** We've updated our library dependencies to take advantage of the latest bugfixes & enhancements. * Remove deleted queries from persisted state **(New)** We now detect & delete queries & segments that have been deleted/disabled from the dashboard. * Add date support to EventProperties **(New)** In older SDKs a developer had to manually format a datetime object to a String (in ISO 9601), we've added date support for EventProperties so that this will happen automatically. * Add appnexus support to add permutive targeting **(New)** We've added preliminary support for ad targeting using the AppNexus SDK with our new appnexus addon library. * Add OS/Script/App info to error reports **(New)** When we report an error to our endpoints we now include additional information to help us diagnose issues: The operating system version, the segmentation queries version that is being executed as well as information on the Application (version & identifier). * Limit deferred functions upon startup **(New)** While the SDK is initialising, we defer execution of public function calls until this has completed. This was previously unlimited, we have put in a cap so that this does not become unbounded. * Add pagetracking API & deprecate context APIs **(New)** The PageTracker API gives support for Pageview and PageviewEngagementAggregate events. The page's context (url/title/referrer) are now tied to a Page, rather than a global Permutive setting. Using the PageTracker API will allow for better reporting & better visibility of engagement on the Android SDK. As a result, we would recommend using PageTracker rather than EventTracker for page related events. As a general rule: if an event has a url/title/referrer - it should probably be tracked by the PageTracker object. The global context methods setTitle/setUrl/setReferrer are now deprecated as a result, and we have stopped persisting these values. * Fix illegal state in db when reading **(Fix)** A small percentage (around 0.5%) of users have reported an IllegalStateException under certain circumstances. Previously we would halt segmentation & disable the SDK for these users, for 1.4.0 we have a fix so that this will no longer happen. * Fix regex matching when disabling **(Fix)** We have made our regular expression matching more straightforward in the event that we have to disable a deployment. * Fix consumer proguard typo **(Fix)** Some setups of proguard have stripped away functions that we are using internally. Although we had a @Keep clause on the function, it is still possible that it can be stripped away. We have updated our consumer-proguard so that this is fixed. * fix issue when migrating from older versions Upgrading from older versions of this SDK can result in a migration issue, we recommend using version 1.3.1 which has a fix for this issue. * Add ability to remotely disable by application, os, or sdk version **(New)** * Remove dependency on core library for google ads library **(New)** * Add third party data usage reporting support **(New)** * Make engine events session\_id & user\_id optional **(Fix)** * Fix stack size issue for Dalvik VMs **(Fix)** Segmentation may not occur for OSes using Dalvik VMs, we recommend using version 1.2.0 which has a fix for this issue. * Use Rhino as the js engine **(New)** * Non-beta release of the Android SDK * Correctly handle date time when the format is incorrect **(Fix)** * Reduce memory overhead for db so that it performs well on low end systems **(Fix)** * Only update event server time when posting events **(Fix)** # Troubleshooting Source: https://docs.permutive.com/sdks/mobile/android/troubleshooting/common-errors Solutions to common issues when integrating the Permutive Android SDK This guide covers common issues you may encounter when integrating the Permutive Android SDK and how to resolve them. **Quick Diagnostics:** Enable debug logging before troubleshooting: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) ``` Or via ADB: ```bash theme={"dark"} adb shell setprop log.tag.Permutive VERBOSE adb logcat -s Permutive ``` ## Initialization Issues **Symptoms:** ``` D/Permutive: Error fetching configuration - please check that your workspace id & API key is correct, or contact customer support (Http error: 404) ``` **Causes:** 1. Incorrect Workspace ID or API Key 2. Using deprecated `projectId` instead of `workspaceId` 3. Android not enabled for your workspace **Solutions:** **1. Verify Credentials** ```kotlin theme={"dark"} // ❌ Wrong: Using deprecated projectId val permutive = Permutive.Builder() .projectId(UUID.fromString("...")) // DEPRECATED .build() // ✅ Correct: Use workspaceId val permutive = Permutive( context = this, workspaceId = UUID.fromString("YOUR_WORKSPACE_ID"), apiKey = UUID.fromString("YOUR_API_KEY") ) ``` **2. Check Credentials Format** Ensure your IDs are valid UUIDs (format: 8-4-4-4-12 hexadecimal digits): ```kotlin theme={"dark"} // Example: "550e8400-e29b-41d4-a716-446655440000" // ❌ Wrong: Not a UUID workspaceId = UUID.fromString("12345") // Throws exception // ✅ Correct: Valid UUID workspaceId = UUID.fromString("550e8400-e29b-41d4-a716-446655440000") ``` **3. Enable Android** Contact your Customer Success Manager to verify Android is enabled for your workspace. **Symptoms:** Events tracked multiple times, undefined behavior. **Cause:** Creating more than one `Permutive` instance. **Solution:** Use a singleton pattern: ```kotlin Kotlin theme={"dark"} class MyApplication : Application() { val permutive by lazy { Permutive( context = this, workspaceId = YOUR_WORKSPACE_ID, apiKey = YOUR_API_KEY ) } } // Access from activities class MyActivity : AppCompatActivity() { private val permutive by lazy { (application as MyApplication).permutive } } ``` ```java Java theme={"dark"} public class MyApplication extends Application { private volatile Permutive permutive; public Permutive getPermutive() { if (permutive == null) { synchronized (this) { if (permutive == null) { permutive = new Permutive.Builder() .context(this) .workspaceId(YOUR_WORKSPACE_ID) .apiKey(YOUR_API_KEY) .build(); } } } return permutive; } } ``` ## Event Tracking Issues **Symptoms:** ``` D/Permutive: Error publishing event with name "Pageview": D/Permutive: Code: 1007 D/Permutive: Status: BadRequest D/Permutive: Cause: Schema validation failed with reason(s): [#: extraneous key [publishDate] is not permitted;#/article/categories: expected type: JSONArray, found: String] ``` **Causes:** 1. Property name doesn't match dashboard schema 2. Property type doesn't match dashboard schema 3. Property not defined in dashboard **Solutions:** **1. Check Property Names** (case-sensitive): ```kotlin theme={"dark"} // ❌ Wrong: Typo in property name EventProperties.from("publishDate" to date) // Schema expects "published_at" // ✅ Correct: Exact match with schema EventProperties.from("published_at" to date) ``` **2. Check Property Types:** ```kotlin theme={"dark"} // ❌ Wrong: String instead of Array EventProperties.from("categories" to "sports") // Schema expects List // ✅ Correct: Array type EventProperties.from("categories" to listOf("sports", "football")) ``` **3. Verify Schema in Dashboard:** 1. Log into Permutive dashboard 2. Navigate to Events 3. Find your event type 4. Verify property names and types match your code **Symptoms:** Events show as "Accepted" in logs but don't appear in dashboard. **Causes:** 1. Dashboard filter settings 2. Time lag (events can take up to 5 minutes) 3. Wrong workspace/environment **Solutions:** 1. **Check Logs**: Verify events are accepted: ``` D/Permutive: Published events with names (Pageview) (Accepted: 1 / 1) ``` 2. **Wait**: Events may take up to 5 minutes to appear 3. **Check Dashboard Filters**: * Verify date range includes now * Check workspace selection * Clear any active filters 4. **Verify Environment**: Ensure you're using production workspace ID **Symptoms:** ``` IllegalArgumentException: Invalid event name "My Event": must contain only the characters [a-zA-Z0-9_] ``` **Cause:** Event name contains invalid characters. **Solution:** Event names must contain only: `a-z`, `A-Z`, `0-9`, `_` ```kotlin theme={"dark"} // ❌ Wrong: Contains spaces and special characters tracker.track("My Event!", properties) tracker.track("page-view", properties) // ✅ Correct: Only valid characters tracker.track("MyEvent", properties) tracker.track("page_view", properties) tracker.track("PageView123", properties) ``` ## Identity Issues **Symptoms:** Setting identity doesn't merge user data from other devices. **Causes:** 1. Network connectivity issues 2. Alias not previously used 3. Timing - resolution takes a moment **Solutions:** 1. **Check Logs**: ``` D/Permutive: Identified user with aliases: email_sha256, internal_id ``` 2. **Verify Network**: Ensure device has connectivity 3. **Wait**: Identity resolution isn't instant, allow a few seconds 4. **Debug**: ```kotlin theme={"dark"} permutive.setDeveloperMode(true) permutive.setIdentity( listOf(Alias.create("email_sha256", emailHash, 0)) ) // Check logs for "Identified user" message ``` **Problem:** Accidentally sending personally identifiable information. **Solution:** Always hash PII before setting as identity: ```kotlin theme={"dark"} import java.security.MessageDigest fun hashEmail(email: String): String { val normalized = email.trim().lowercase() val bytes = MessageDigest.getInstance("SHA-256") .digest(normalized.toByteArray()) return bytes.joinToString("") { "%02x".format(it) } } // ❌ Wrong: Plain text email permutive.setIdentity( listOf(Alias.create("email", "user@example.com", 0)) // DON'T! ) // ✅ Correct: Hashed email val emailHash = hashEmail("user@example.com") permutive.setIdentity( listOf(Alias.create("email_sha256", emailHash, 0)) ) ``` ## Cohort and Activation Issues **Symptoms:** `currentCohorts` returns empty list. **Causes:** 1. SDK just initialized - cohorts haven't synced yet 2. User hasn't triggered events to qualify for cohorts 3. Network issues **Solutions:** 1. **Wait for Initialization**: ```kotlin theme={"dark"} // Don't check cohorts immediately Handler(Looper.getMainLooper()).postDelayed({ val cohorts = permutive.currentCohorts Log.d("Debug", "Cohorts: ${cohorts.size}") }, 3000) ``` 2. **Use TriggersProvider**: For reactive updates: ```kotlin theme={"dark"} val trigger = triggersProvider.triggerAction("cohort_id") { isInCohort -> // Called when cohort status changes } ``` 3. **Track Events**: User needs to trigger events to qualify for cohorts **Symptoms:** `dfp_contextual` or `appnexus_adserver_contextual` are empty. **Causes:** 1. Feature not enabled 2. SDK version too old 3. Not tracking pages with URLs 4. Classification in progress **Solutions:** 1. **Check SDK Version**: * Core: 1.10.0+ * Google Ads: 2.2.0+ * AppNexus: 1.7.0+ 2. **Verify Feature Enabled**: Contact Customer Success Manager 3. **Track with URLs**: ```kotlin theme={"dark"} // ❌ Wrong: No URL val pageTracker = permutive.trackPage(title = "Article Title") // ✅ Correct: Include URL val pageTracker = permutive.trackPage( title = "Article Title", url = Uri.parse("https://example.com/article") ) ``` 4. **Wait for Classification**: First analysis takes 1-2 seconds 5. **Check URL Accessibility**: URL must be publicly accessible ## Ad Integration Issues **Symptoms:** Ads load but don't seem to be targeted. **Causes:** 1. Not using add-on library helper methods 2. Cohorts not ready when ad request made 3. Dashboard activation configuration **Solutions:** **1. Use Helper Methods** ```kotlin theme={"dark"} // ❌ Wrong: Manual ad request without Permutive val adRequest = AdManagerAdRequest.Builder().build() // ✅ Correct: Use Permutive helper val adRequest = AdManagerAdRequest.Builder() .addPermutiveTargeting(permutive) .build() ``` **2. Verify Logs** Look for: ``` D/Permutive: Permutive segments appended to Google Ad request: 123, 456, 789 ``` If this doesn't appear, cohorts aren't being added. **3. Check Activations** ```kotlin theme={"dark"} val activations = permutive.currentActivations val gamCohorts = activations["dfp"] if (gamCohorts.isNullOrEmpty()) { Log.w("Debug", "No GAM activations available") // Either cohorts not ready or not activated for GAM } ``` ## Performance Issues **Symptoms:** App performance degrades after SDK integration. **Causes:** 1. Creating multiple Permutive instances 2. Not closing PageTrackers/MediaTrackers 3. Memory leaks from unclosed TriggerActions **Solutions:** **1. Use Singleton** (see "Multiple Permutive instances detected" above) **2. Always Close Trackers** ```kotlin theme={"dark"} class MyActivity : AppCompatActivity() { private lateinit var pageTracker: PageTracker override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) pageTracker = permutive.trackPage(...) } override fun onDestroy() { super.onDestroy() pageTracker.close() // IMPORTANT! } } ``` **3. Close Triggers** ```kotlin theme={"dark"} class MyActivity : AppCompatActivity() { private val triggers = mutableListOf() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) triggers.add(triggersProvider.triggerAction("cohort") { /*...*/ }) } override fun onDestroy() { super.onDestroy() triggers.forEach { it.close() } // IMPORTANT! triggers.clear() } } ``` **Symptoms:** App memory usage grows over time. **Cause:** Not closing SDK resources. **Solution:** Use Android Studio's Profiler to identify leaks, then ensure all SDK resources are closed: * `PageTracker.close()` * `MediaTracker.stop()` * `AdTracker.completion()` * `TriggerAction.close()` ## Build Issues **Symptoms:** App crashes in release build with minification enabled. **Cause:** SDK classes being stripped by ProGuard/R8. **Solution:** The SDK includes consumer ProGuard rules automatically. If you're still experiencing issues: 1. **Verify consumer rules are applied**: ```groovy theme={"dark"} android { buildTypes { release { minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } } ``` 2. **Test with debug logging**: ```kotlin theme={"dark"} if (BuildConfig.DEBUG) { permutive.setDeveloperMode(true) } ``` **Symptoms:** ``` Duplicate class com.permutive.android.X found in modules... ``` **Causes:** 1. Multiple SDK versions in dependencies 2. Transitive dependency conflicts **Solutions:** **1. Check Dependencies** ```bash theme={"dark"} ./gradlew app:dependencies ``` Look for multiple versions of Permutive libraries. **2. Force Version Resolution** ```kotlin theme={"dark"} configurations.all { resolutionStrategy { force("com.permutive.android:core:1.12.0") force("com.permutive.android:google-ads:2.2.0") } } ``` ## Debugging Tips ```kotlin theme={"dark"} // Enable Permutive debug logs permutive.setDeveloperMode(true) // Enable network logging (if using OkHttp) val loggingInterceptor = HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY } ``` ```kotlin theme={"dark"} // Log SDK version Log.d("Debug", "Permutive SDK Version: ${BuildConfig.VERSION_NAME}") ``` ```kotlin theme={"dark"} val metrics = permutive.currentMetrics Log.d("Debug", "SDK Metrics: $metrics") ``` ## Getting Help If you're still experiencing issues: 1. Enable debug logging and capture logs 2. Note the SDK version you're using 3. Document steps to reproduce the issue 4. Gather SDK version, device info, and error logs **Contact Support:** * [Support](mailto:support@permutive.com) Comprehensive integration verification Upgrade to the latest SDK version # Cohorts and Activations Source: https://docs.permutive.com/sdks/mobile/ios/core-concepts/cohorts-and-activations Understanding user segmentation and platform-specific targeting Understanding cohorts and activations is fundamental to using the Permutive SDK effectively. ## What are Cohorts? ### Cohort Types ## What are Activations? ### Available Activation Types ## Cohorts vs. Activations In the SDK, access cohorts via `cohorts` and activations via `activations`. **Example:** ``` User's Cohorts: ["sports_enthusiast", "premium_subscriber", "mobile_user", "frequent_visitor"] Activations: - dfp: ["sports_enthusiast", "premium_subscriber"] // Only 2 activated for GAM - freewheel: ["sports_enthusiast"] // Only 1 activated for Freewheel ``` ## Accessing Cohorts and Activations Get all cohorts the user currently belongs to: ```swift Swift theme={"dark"} let currentCohorts: Set = Permutive.shared.cohorts for cohortId in currentCohorts { print("User is in cohort: \(cohortId)") } ``` ```objectivec Objective-C theme={"dark"} NSSet *currentCohorts = [Permutive.shared cohorts]; for (NSString *cohortId in currentCohorts) { NSLog(@"User is in cohort: %@", cohortId); } ``` Get cohorts activated for specific platforms: ```swift Swift theme={"dark"} let activations: [String: [String]] = Permutive.shared.activations // Get Google Ad Manager activations let gamActivations = activations["dfp"] ?? [] // Get AppNexus activations let appNexusActivations = activations["appnexus_adserver"] ?? [] // Get Freewheel activations let freewheelActivations = activations["freewheel"] ?? [] // Get contextual activations let gamContextual = activations["dfp_contextual"] ?? [] ``` ```objectivec Objective-C theme={"dark"} NSDictionary *> *activations = [Permutive.shared activations]; // Get Google Ad Manager activations NSArray *gamActivations = activations[@"dfp"] ?: @[]; // Get AppNexus activations NSArray *appNexusActivations = activations[@"appnexus_adserver"] ?: @[]; ``` For real-time cohort changes, use `TriggerProvider`: ```swift Swift theme={"dark"} var trigger: TriggerAction? func watchCohort() { trigger = Permutive.shared.triggerProvider?.action( boolFor: ["premium_subscriber"], action: { query, isInCohort in if isInCohort { self.showPremiumFeatures() } else { self.hidePremiumFeatures() } } ) } // Release when done deinit { trigger = nil } ``` ```objectivec Objective-C theme={"dark"} @property (nonatomic, strong) PermutiveTriggerAction *trigger; - (void)watchCohort { NSSet *cohorts = [NSSet setWithObject:@"premium_subscriber"]; self.trigger = [Permutive.shared.triggerProvider actionWithBoolFor:cohorts action:^(NSString *cohort, BOOL isInCohort) { if (isInCohort) { [self showPremiumFeatures]; } else { [self hidePremiumFeatures]; } }]; } ``` Complete documentation for reactive updates `cohorts` and `activations` return **snapshot values** at the time they're called. For real-time updates, use TriggerProvider. ## Use Cases ```swift Swift theme={"dark"} class PersonalizedHomeViewController: UIViewController { func personalizeContent() { let cohorts = Permutive.shared.cohorts if cohorts.contains("premium_subscriber") { showPremiumContent() } else if cohorts.contains("sports_enthusiast") { showSportsRecommendations() } else if cohorts.contains("tech_reader") { showTechRecommendations() } else { showGeneralContent() } } } ``` ```objectivec Objective-C theme={"dark"} - (void)personalizeContent { NSSet *cohorts = [Permutive.shared cohorts]; if ([cohorts containsObject:@"premium_subscriber"]) { [self showPremiumContent]; } else if ([cohorts containsObject:@"sports_enthusiast"]) { [self showSportsRecommendations]; } else if ([cohorts containsObject:@"tech_reader"]) { [self showTechRecommendations]; } else { [self showGeneralContent]; } } ``` ```swift theme={"dark"} class ExperimentalFeatureViewController: UIViewController { override func viewDidLoad() { super.viewDidLoad() let cohorts = Permutive.shared.cohorts // Use cohort membership as feature flag let enableNewCheckout = cohorts.contains("checkout_experiment_v2") if enableNewCheckout { setupNewCheckoutUI() } else { setupClassicCheckoutUI() } } } ``` Activations are used with ad targeting: ```swift Swift theme={"dark"} // Google Ad Manager let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker ) bannerView.load(adRequest) ``` ```objectivec Objective-C theme={"dark"} // Google Ad Manager GAMRequest *adRequest = [GAMRequest request]; adRequest.customTargeting = [Permutive.shared googleCustomTargetingWithAdTargetable:self.pageTracker]; [self.bannerView loadRequest:adRequest]; ``` ```swift theme={"dark"} class AnalyticsHelper { func logUserSegments() { let cohorts = Permutive.shared.cohorts // Log to your analytics platform Analytics.setUserProperty( "permutive_cohorts", value: cohorts.joined(separator: ",") ) Analytics.logEvent( "cohort_count", parameters: ["count": cohorts.count] ) } func getActivationInfo() -> [String: Any] { let activations = Permutive.shared.activations return [ "gam_cohort_count": activations["dfp"]?.count ?? 0, "appnexus_cohort_count": activations["appnexus_adserver"]?.count ?? 0, "has_contextual": (activations["dfp_contextual"]?.isEmpty == false) ] } } ``` ## Contextual Cohorts Contextual cohorts are generated in real-time based on content being viewed. They require SDK version 2.0.0+ and feature enablement by your CSM. ```swift Swift theme={"dark"} // Track a page with URL let properties = try? EventProperties([ "category": "automotive", "subcategory": "electric_vehicles" ]) let context = Context( title: "Electric Vehicle Buying Guide", url: URL(string: "https://example.com/articles/ev-buying-guide"), referrer: nil ) let pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) try? pageTracker?.resume() // Contextual cohorts appear in activations let contextualCohorts = Permutive.shared.activations["dfp_contextual"] ?? [] // Example: ["automotive_ev", "automotive_buying_guides", "sustainability"] // Used automatically in ad requests let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker ) ``` ```objectivec Objective-C theme={"dark"} // Track a page with URL NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"category": @"automotive", @"subcategory": @"electric_vehicles"} error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Electric Vehicle Buying Guide" url:[NSURL URLWithString:@"https://example.com/articles/ev-buying-guide"] referrer:nil]; NSObject *pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; [pageTracker resumeAndReturnError:nil]; // Contextual cohorts appear in activations NSArray *contextualCohorts = [Permutive.shared activations][@"dfp_contextual"] ?: @[]; ``` Complete contextual cohorts documentation ## tvOS Considerations **tvOS Note:** Cohorts and activations work identically on tvOS. The same APIs are available, and cohort data syncs across all Apple platforms when identity is set. ## Troubleshooting **Problem:** `cohorts` returns an empty set. **Solutions:** * Wait a few seconds after initialization * Track some events to generate data * Use TriggerProvider for reactive updates * Enable debug logging to see sync status * Verify cohorts are configured in your dashboard **Problem:** User is in a cohort but it doesn't appear in activations. **Cause:** Not all cohorts are activated for all platforms. This is configured in your Permutive dashboard. **Solution:** Check your dashboard configuration or contact your Customer Success Manager. **Problem:** `dfp_contextual` activations are empty. **Solutions:** * Verify feature is enabled with your CSM * Update to SDK 2.0.0+ * Ensure you're using PageTracker with valid URLs * Verify the URL is publicly accessible * Check debug logs for classification errors ## Best Practices * Use `cohorts` for one-time checks * Use TriggerProvider for reactive updates * Check activation keys exist before accessing * Handle empty sets gracefully * Log cohorts for debugging (in development only) * Cache cohort checks that are expensive to re-evaluate * Poll `cohorts` repeatedly (use TriggerProvider instead) * Assume cohorts will be available immediately after initialization * Hard-code cohort IDs without checking dashboard * Share PII in cohort names or IDs * Cache cohorts for long periods (they can change) ## Related Documentation Reactive cohort updates Content-based segmentation GAM integration AppNexus integration # Contextual Data Source: https://docs.permutive.com/sdks/mobile/ios/core-concepts/contextual-data Real-time content-based segmentation for privacy-friendly targeting Contextual data enables real-time content-based segmentation without relying on historical user behavior. The SDK analyzes content users are viewing and generates contextual cohorts instantly. ## Overview In the iOS SDK, contextual cohorts are generated in real-time when you track pages or videos with URLs. The SDK automatically includes these cohorts in ad requests alongside behavioral cohorts. ## Requirements * **SDK Version:** 2.0.0 or higher * **Platform:** iOS 12.0+ / tvOS 12.0+ * **Feature Enablement:** Contact your Customer Success Manager **Feature Activation Required:** Contextual content classification must be enabled by Permutive for your workspace. Please contact your Customer Success Manager if you'd like to use this feature. ## How It Works Use `PageTracker` with a content URL Permutive analyzes the content at the URL (page title, main text, keywords, IAB categories, sentiment) Content-based segments are created in real-time Contextual cohorts automatically included in ad requests *** ## Implementation ### Page Tracking with Contextual Data Simply include URLs when tracking pages - contextual analysis happens automatically: ```swift Swift theme={"dark"} import UIKit import Permutive_iOS class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() // Create event properties let properties = try? EventProperties([ "category": "automotive", "subcategory": "electric_vehicles", "author": "Jane Smith" ]) // Track page with URL - contextual analysis automatic let context = Context( title: "Complete Guide to Electric Vehicles", url: URL(string: "https://example.com/articles/electric-vehicle-guide"), referrer: URL(string: "https://example.com/automotive") ) pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) pageTracker?.pause() } deinit { pageTracker?.stop() } } ``` ```objectivec Objective-C theme={"dark"} #import "ArticleViewController.h" @import Permutive_iOS; @interface ArticleViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; // Create event properties NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"category": @"automotive", @"subcategory": @"electric_vehicles", @"author": @"Jane Smith" } error:&error]; // Track page with URL - contextual analysis automatic PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Complete Guide to Electric Vehicles" url:[NSURL URLWithString:@"https://example.com/articles/electric-vehicle-guide"] referrer:[NSURL URLWithString:@"https://example.com/automotive"]]; self.pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.pageTracker pause]; } - (void)dealloc { [self.pageTracker stop]; } @end ``` *** ## Accessing Contextual Cohorts Contextual cohorts are automatically included in activations with special keys: ### In Current Activations ```swift Swift theme={"dark"} let activations = Permutive.shared.activations // Google Ad Manager contextual cohorts let gamContextual = activations["dfp_contextual"] ?? [] // Example: ["automotive_ev", "automotive_reviews", "tech_innovation"] // Xandr/AppNexus contextual cohorts let xandrContextual = activations["appnexus_adserver_contextual"] ?? [] // Log contextual cohorts print("GAM contextual cohorts: \(gamContextual)") ``` ```objectivec Objective-C theme={"dark"} NSDictionary *activations = [Permutive.shared activations]; // Google Ad Manager contextual cohorts NSArray *gamContextual = activations[@"dfp_contextual"] ?: @[]; // Xandr/AppNexus contextual cohorts NSArray *xandrContextual = activations[@"appnexus_adserver_contextual"] ?: @[]; NSLog(@"GAM contextual cohorts: %@", gamContextual); ``` ### In Ad Requests Contextual cohorts are automatically included when using `googleCustomTargeting`: ```swift Swift theme={"dark"} // Contextual cohorts automatically added with key "prmtvctx" let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker // Include PageTracker for view ID ) bannerView.load(adRequest) // The resulting ad request includes: // - permutive: ["123", "456"] // Behavioral cohorts // - prmtvctx: ["cabf", "cabc", "bzwu"] // Contextual cohorts // - puid: "user_id" // - ptime: "timestamp" // - prmtvvid: "view_id" ``` ```objectivec Objective-C theme={"dark"} // Contextual cohorts automatically added GAMRequest *adRequest = [GAMRequest request]; adRequest.customTargeting = [Permutive.shared googleCustomTargetingWithAdTargetable:self.pageTracker]; [self.bannerView loadRequest:adRequest]; ``` *** ## Performance Considerations ### Content Analysis Timing * **First analysis:** May take 1-2 seconds for initial content fetch and analysis * **Cached results:** Subsequent views of the same URL use cached analysis * **Background processing:** Analysis happens asynchronously, doesn't block UI * **Network required:** Content classification requires network connectivity ### Best Practices for Performance ```swift Swift theme={"dark"} // ✅ Good: Create PageTracker early, analysis starts immediately override func viewDidLoad() { super.viewDidLoad() // Start tracking (and analysis) as early as possible pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) // Load your content loadArticleContent() } ``` ```swift Swift theme={"dark"} // ❌ Avoid: Delaying page tracking override func viewDidLoad() { super.viewDidLoad() loadArticleContent() // Tracking delayed - contextual cohorts may not be ready for early ads DispatchQueue.main.asyncAfter(deadline: .now() + 5) { self.pageTracker = try? Permutive.shared.createPageTracker(...) } } ``` *** ## Privacy and Compliance ### Privacy-Friendly Targeting ### Data Sent for Analysis When tracking a page with a URL: * **URL** - The page URL for content fetching * **Title** - Page title (if provided) * **No PII** - No personal information sent for classification The URL should be **publicly accessible** for content analysis to work. *** ## Error Handling ### Classification Failures Contextual classification may fail if: * URL is not publicly accessible * Content is behind a paywall or login * Network connectivity issues * Server-side analysis errors **The SDK handles failures gracefully:** ```swift Swift theme={"dark"} // If contextual classification fails: // 1. Behavioral cohorts still work // 2. Events still tracked // 3. No error surfaced to app // 4. Contextual activations will be empty let contextualCohorts = Permutive.shared.activations["dfp_contextual"] ?? [] if contextualCohorts.isEmpty { // This is OK - may be: // - Feature not enabled // - Classification in progress // - Classification failed // - No URL tracked yet // Behavioral targeting still works let behavioralCohorts = Permutive.shared.activations["dfp"] ?? [] } ``` ```objectivec Objective-C theme={"dark"} NSArray *contextualCohorts = [Permutive.shared activations][@"dfp_contextual"] ?: @[]; if (contextualCohorts.count == 0) { // Behavioral targeting still works NSArray *behavioralCohorts = [Permutive.shared activations][@"dfp"] ?: @[]; } ``` ### Debugging Classification Enable debug logging to see classification status: ```swift theme={"dark"} options.logModes = LogMode.all // Look for logs like: // Permutive: [info] Contextual classification requested for URL: https://... // Permutive: [info] Contextual cohorts received: [cohort1, cohort2, ...] // Permutive: [error] Contextual classification failed: ``` *** ## Use Cases ### Content-Aligned Advertising ```swift Swift theme={"dark"} class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() // Track article page let context = Context( title: article.title, url: URL(string: article.url), referrer: nil ) pageTracker = try? Permutive.shared.createPageTracker( properties: nil, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() // Load ad - contextual cohorts automatically included loadAd() } private func loadAd() { // Contextual cohorts ensure ad is relevant to article content let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker ) bannerView.load(adRequest) } } ``` ```objectivec Objective-C theme={"dark"} - (void)viewDidLoad { [super viewDidLoad]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:self.article.title url:[NSURL URLWithString:self.article.url] referrer:nil]; self.pageTracker = [Permutive.shared createPageTrackerWithProperties:nil context:context error:nil]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; [self loadAd]; } - (void)loadAd { GAMRequest *adRequest = [GAMRequest request]; adRequest.customTargeting = [Permutive.shared googleCustomTargetingWithAdTargetable:self.pageTracker]; [self.bannerView loadRequest:adRequest]; } ``` ### Contextual + Behavioral Targeting Combine contextual and behavioral cohorts for powerful targeting: ```swift theme={"dark"} let activations = Permutive.shared.activations // Behavioral: User interests over time let behavioral = activations["dfp"] ?? [] // Example: ["sports_enthusiast", "premium_subscriber"] // Contextual: Current content let contextual = activations["dfp_contextual"] ?? [] // Example: ["sports_soccer", "sports_worldcup"] // Both automatically included in ad requests let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker ) // Ad platform receives: // - permutive: ["sports_enthusiast", "premium_subscriber"] // - prmtvctx: ["sports_soccer", "sports_worldcup"] // // Result: Highly targeted ad for soccer content to a sports enthusiast ``` *** ## Contextual vs. Behavioral Cohorts In the SDK, contextual cohorts use activation keys `dfp_contextual` and `appnexus_adserver_contextual`, while behavioral cohorts use `dfp` and `appnexus_adserver`. ### When to Use Each **Use Behavioral Cohorts When:** * Building long-term audience segments * Retargeting campaigns * Personalization based on user history * Lookalike modeling **Use Contextual Cohorts When:** * Real-time content alignment needed * Privacy regulations are strict * New users without history * Brand safety is critical * Cookie-less environment **Use Both When:** * Maximum targeting precision needed * Combining user intent (contextual) with user interests (behavioral) * Premium inventory requires both signals *** ## tvOS Considerations **tvOS Note:** Contextual data works identically on tvOS. Provide URLs in the Context when creating PageTrackers for content analysis. *** ## Troubleshooting **Problem:** `dfp_contextual` is empty or not present. **Possible Causes & Solutions:** 1. **Feature not enabled** * Contact Customer Success Manager to enable 2. **SDK version too old** * Update to SDK 2.0.0+ 3. **No URL tracked** * Ensure you're using `PageTracker` with a Context that has a valid URL 4. **Classification in progress** * First analysis may take 1-2 seconds * Check again after a moment 5. **URL not accessible** * Ensure URL is publicly accessible * Remove authentication requirements for analysis 6. **Network issues** * Check device connectivity * Look for network errors in logs **Problem:** Contextual cohorts not appearing before ads load. **Solutions:** * Start page tracking earlier in view lifecycle * Consider delaying ad request slightly if contextual is critical * Use behavioral cohorts as fallback **Problem:** Cohorts don't match content. **Possible Causes:** * URL points to different content than displayed * Content changed since classification * Cache from previous analysis **Solutions:** * Ensure URL matches actual content * Use unique URLs for different content * Wait for cache expiry or contact support to invalidate *** ## Best Practices ### Do * Track pages with URLs as early as possible * Use publicly accessible URLs * Ensure URLs are stable and won't change * Test with debug logging enabled * Use unique URLs for different content * Combine with behavioral targeting for best results ### Don't * Use authentication-protected URLs * Track pages without URLs (contextual won't work) * Expect instant results (allow 1-2 seconds) * Rely solely on contextual for returning users * Use duplicate URLs for different content *** ## Related Documentation Understanding user segmentation PageTracker guide GAM integration AppNexus integration # Event Properties Source: https://docs.permutive.com/sdks/mobile/ios/core-concepts/event-properties Structure and validate event metadata Event properties allow you to attach metadata to events for richer segmentation and targeting. The iOS SDK uses the `EventProperties` class to encapsulate this data with type safety. ## Creating Properties `EventProperties` wraps a dictionary with type validation. Invalid types throw an exception on construction. ```swift Swift theme={"dark"} do { let properties = try EventProperties([ "category": "sports", "author": "John Doe", "published": true, "word_count": 1500 ]) try Permutive.shared.track(event: "ArticleView", properties: properties) } catch { print("Failed to create properties: \(error)") } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"category": @"sports", @"author": @"John Doe", @"published": @YES, @"word_count": @1500 } error:&error]; if (error != nil) { NSLog(@"Failed to create properties: %@", error); return; } [Permutive.shared trackWithEvent:@"ArticleView" properties:properties error:&error]; ``` ## Supported Types `EventProperties` supports the following value types: | Type | Swift | Objective-C | Example | | ------------- | ----------------- | -------------------------- | ------------ | | String | `String` | `NSString` | `"sports"` | | Integer | `Int` | `NSNumber` | `42` | | Float | `Float`, `Double` | `NSNumber` | `3.14` | | Boolean | `Bool` | `NSNumber` | `true` | | Date | `Date` | `NSDate` | `Date()` | | Nested Object | `EventProperties` | `PermutiveEventProperties` | See below | | Array | `[T]` | `NSArray` | `["a", "b"]` | ### Nested Objects ```swift Swift theme={"dark"} let author = try EventProperties([ "name": "Jane Smith", "id": "author_123" ]) let properties = try EventProperties([ "title": "Article Title", "author": author // Nested EventProperties ]) ``` ```objectivec Objective-C theme={"dark"} PermutiveEventProperties *author = [[PermutiveEventProperties alloc] init:@{@"name": @"Jane Smith", @"id": @"author_123"} error:nil]; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"title": @"Article Title", @"author": author} error:nil]; ``` ### Arrays ```swift Swift theme={"dark"} let properties = try EventProperties([ "tags": ["technology", "mobile", "ios"], "category_ids": [1, 2, 3], "featured": true ]) ``` ```objectivec Objective-C theme={"dark"} PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"tags": @[@"technology", @"mobile", @"ios"], @"category_ids": @[@1, @2, @3], @"featured": @YES } error:nil]; ``` ## Event Enrichment Events can be enriched with server-side data using special property values: ### Available Enrichment Values | Value | Description | | ----------------------------------------------- | ------------------------- | | `EventProperties.geoInfoValue` | Geographic location data | | `EventProperties.ispInfoValue` | ISP information | | `EventProperties.ipHashInfoValue` | Hashed IP address | | `EventProperties.alchemyConceptsValue` | Watson NLU concepts | | `EventProperties.alchemyEntitiesValue` | Watson NLU entities | | `EventProperties.alchemyKeywordsValue` | Watson NLU keywords | | `EventProperties.alchemyTaxonomyValue` | Watson NLU taxonomy | | `EventProperties.alchemyDocumentEmotionValue` | Watson document emotion | | `EventProperties.alchemyDocumentSentimentValue` | Watson document sentiment | | `EventProperties.alchemyTaxonomyLabelsValue` | Watson taxonomy labels | | `EventProperties.alchemyEntityNamesValue` | Watson entity names | ### Location and ISP Enrichment ```swift Swift theme={"dark"} do { let properties = try EventProperties([ "geo_info": EventProperties.geoInfoValue, "isp_info": EventProperties.ispInfoValue, "form_id": "contact_form" ]) try Permutive.shared.track(event: "FormSubmission", properties: properties) } catch { print("Error: \(error)") } ``` ```objectivec Objective-C theme={"dark"} PermutiveEventProperties *properties = [PermutiveEventProperties new]; [properties setValue:PermutiveEventProperties.geoInfoValue forKey:@"geo_info"]; [properties setValue:PermutiveEventProperties.ispInfoValue forKey:@"isp_info"]; [properties setValue:@"contact_form" forKey:@"form_id"]; NSError *error = nil; [Permutive.shared trackWithEvent:@"FormSubmission" properties:properties error:&error]; ``` ### Watson Content Analysis (Standard Cohorts) For Standard Cohorts support, include Watson taxonomy labels: ```swift Swift theme={"dark"} // Create nested taxonomy structure let urlTaxonomy = try EventProperties([ "taxonomy_labels": EventProperties.alchemyTaxonomyLabelsValue ]) let properties = try EventProperties([ "classifications_watson": urlTaxonomy ]) // Create PageTracker with these properties let context = Context( title: "Article Title", url: URL(string: "https://example.com/article"), referrer: nil ) let pageTracker = try Permutive.shared.createPageTracker( properties: properties, context: context ) ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; PermutiveEventProperties *urlTaxonomy = [[PermutiveEventProperties alloc] init:@{@"taxonomy_labels": PermutiveEventProperties.alchemyTaxonomyLabelsValue} error:&error]; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"classifications_watson": urlTaxonomy} error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Article Title" url:[NSURL URLWithString:@"https://example.com/article"] referrer:nil]; NSObject *pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; ``` **Standard Cohorts Requirement:** For Standard Cohorts to work, both a valid URL in the Context and the `classifications_watson.taxonomy_labels` property must be set. Contact your Customer Success Manager (CSM) to enable this feature. ## Schema Validation Event properties **must match** the schema defined in your Permutive dashboard. Mismatches result in event rejection. ### Common Schema Errors Enable debug logging to see schema validation errors: ```swift theme={"dark"} options.logModes = LogMode.all ``` Error messages look like: ``` Permutive: [error] Encountered 1 event rejection! Permutive: [error] Schema validation failed with reason(s): [#: extraneous key [invalid_key] is not permitted] ``` ### Property Name Rules Property names must follow these rules: * Only alphanumeric characters and underscores: `[a-zA-Z0-9_]` * Cannot start with a number * Case-sensitive ```swift theme={"dark"} "category" // ✅ "word_count" // ✅ "articleId" // ✅ "section_2" // ✅ ``` ```swift theme={"dark"} "word-count" // ❌ Hyphen not allowed "2_section" // ❌ Cannot start with number "my property" // ❌ Spaces not allowed ``` ## Using Properties with PageTracker Properties passed to `PageTracker` are included with automatically generated events: ```swift Swift theme={"dark"} class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() let properties = try? EventProperties([ "category": "technology", "subcategory": "mobile", "author_id": "author_456", "premium": true ]) let context = Context( title: "iOS Development Guide", url: URL(string: "https://example.com/ios-guide"), referrer: nil ) // Properties included with Pageview and PageViewComplete events pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() } func onLinkClick(linkName: String) { // Additional properties for specific events let clickProperties = try? EventProperties([ "link_name": linkName, "position": "header" ]) try? pageTracker?.track(event: "LinkClick", properties: clickProperties) } } ``` ```objectivec Objective-C theme={"dark"} @interface ArticleViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"category": @"technology", @"subcategory": @"mobile", @"author_id": @"author_456", @"premium": @YES } error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"iOS Development Guide" url:[NSURL URLWithString:@"https://example.com/ios-guide"] referrer:nil]; self.pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; } - (void)onLinkClick:(NSString *)linkName { NSError *error = nil; PermutiveEventProperties *clickProperties = [[PermutiveEventProperties alloc] init:@{@"link_name": linkName, @"position": @"header"} error:&error]; [self.pageTracker trackWithEvent:@"LinkClick" properties:clickProperties error:&error]; } @end ``` ## Updating Properties Dynamically For values that change during tracking, use the Objective-C style setter: ```swift theme={"dark"} let properties = EventProperties() properties.setValue("initial_value", forKey: "status") // Later... properties.setValue("updated_value", forKey: "status") ``` ## Best Practices * Match property names and types exactly to your schema * Use consistent property names across your app * Use meaningful, descriptive property names * Validate properties exist in your schema before deploying * Use nested properties for complex structured data * Test with debug logging enabled * Don't include PII in event properties * Don't use dynamic property names that aren't in your schema * Don't include empty or null values unnecessarily * Don't exceed reasonable property counts (keep under 50 per event) * Don't use very large arrays (may impact performance) ## Troubleshooting **Problem:** Console shows schema validation errors. **Solutions:** * Check property names match your dashboard schema exactly * Verify property types are correct (string vs int vs bool) * Remove any extra properties not in the schema * Check for typos in property names **Problem:** Creating EventProperties fails. **Solutions:** * Verify all values are supported types * Ensure no unsupported types like custom objects * Check nested EventProperties are valid **Problem:** Geo/ISP data not appearing. **Solutions:** * Ensure your schema includes the enrichment property * Contact support to verify enrichment is enabled * Check you're using the correct enrichment value constant ## Related Documentation Using properties with PageTracker Tracking custom events Content-based segmentation Common problems and solutions # Identity Management Source: https://docs.permutive.com/sdks/mobile/ios/core-concepts/identity-management Track users across sessions, devices, and platforms with aliases Identity management allows you to track users across different sessions, devices, and platforms by associating multiple identifiers (aliases) with a single user profile. ## Overview In the iOS SDK, you can set aliases using the `setIdentities(aliases:)` method. The SDK uses a singleton pattern via `Permutive.shared`. ## Key Concepts ## Setting Identity For apps with a single identifier type: ```swift Swift theme={"dark"} do { let alias = Alias(tag: "internal_id", identity: userId) try Permutive.shared.setIdentities(aliases: [alias]) } catch { print("Failed to set identity: \(error)") } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; PermutiveAlias *alias = [[PermutiveAlias alloc] initWithTag:@"internal_id" identity:userId]; [Permutive.shared setIdentitiesWithAliases:@[alias] error:&error]; ``` For apps tracking multiple identifier types (email, user ID, etc.): ```swift Swift theme={"dark"} do { let aliases = [ // Highest priority: hashed email Alias(tag: "email_sha256", identity: emailHash), // Medium priority: internal user ID Alias(tag: "internal_id", identity: userId, priority: 1), // Lower priority: with expiry date Alias( tag: "session_id", identity: sessionId, priority: 2, expiry: Date().addingTimeInterval(86400 * 30) // 30 days ) ] try Permutive.shared.setIdentities(aliases: aliases) } catch { print("Failed to set identities: \(error)") } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; // Highest priority: hashed email PermutiveAlias *emailAlias = [[PermutiveAlias alloc] initWithTag:@"email_sha256" identity:emailHash]; // Medium priority: internal user ID PermutiveAlias *idAlias = [[PermutiveAlias alloc] initWithTag:@"internal_id" identity:userId priority:1]; // Lower priority: with expiry NSDate *expiry = [NSDate dateWithTimeIntervalSinceNow:86400 * 30]; PermutiveAlias *sessionAlias = [[PermutiveAlias alloc] initWithTag:@"session_id" identity:sessionId priority:2 expiry:expiry]; [Permutive.shared setIdentitiesWithAliases:@[emailAlias, idAlias, sessionAlias] error:&error]; ``` ## Security Best Practices **Always hash** personally identifiable information like email addresses before sending to Permutive. ```swift theme={"dark"} import CryptoKit func hashEmail(_ email: String) -> String { let normalized = email.trimmingCharacters(in: .whitespaces).lowercased() let data = Data(normalized.utf8) let hash = SHA256.hash(data: data) return hash.compactMap { String(format: "%02x", $0) }.joined() } // Usage let emailHash = hashEmail("user@example.com") let alias = Alias(tag: "email_sha256", identity: emailHash) try? Permutive.shared.setIdentities(aliases: [alias]) ``` ```swift theme={"dark"} // DON'T DO THIS - sending PII let alias = Alias(tag: "email", identity: "user@example.com") // WRONG! ``` ### Standard Tag Names | Identifier Type | Recommended Tag | Notes | | -------------------- | -------------------------- | ------------------------------ | | SHA-256 hashed email | `email_sha256` | Most common | | Internal user ID | `internal_id` or `user_id` | Your system's ID | | Vendor identifier | `idfv` | `UIDevice.identifierForVendor` | | Customer ID | `customer_id` | E-commerce systems | | Subscriber ID | `subscriber_id` | Subscription services | ### Reserved Tags Some alias tags are reserved by the SDK and cannot be used: * `appnexus` * `amp` * `gigya` * `sailthru` * `aaid` Aliases with these tags will be ignored. ## IDFA Identity **Permutive recommends against using IDFA** due to Apple's App Tracking Transparency requirements. Consider using `identifierForVendor` or hashed email addresses instead. From v2.6.0, the IDFA, IDFV, and IP address can be **collected automatically** when enabled in your workspace config — no manual code required. See the [v2.6 Migration Guide](/sdks/mobile/ios/guides/migration/v2-6). If you opt into automatic collection, you generally don't need the manual `setIdentityForIDFA` flow below. If you do need to set IDFA manually, use the dedicated `setIdentityForIDFA` method: ```swift theme={"dark"} import AdSupport import AppTrackingTransparency import Permutive_iOS func setIDFAIdentity() { if #available(iOS 14, *) { ATTrackingManager.requestTrackingAuthorization { status in guard status == .authorized else { return } let idfa = ASIdentifierManager.shared().advertisingIdentifier do { try Permutive.shared.setIdentityForIDFA(idfa) } catch { // IDFA may be all zeros (tracking denied) print("Failed to set IDFA: \(error)") } } } } ``` Complete IDFA integration documentation ## Retrieving User ID Get the current Permutive user ID: ```swift Swift theme={"dark"} let userId = Permutive.shared.currentUserId print("Permutive User ID: \(userId)") ``` ```objectivec Objective-C theme={"dark"} NSString *userId = [Permutive.shared currentUserId]; NSLog(@"Permutive User ID: %@", userId); ``` ## Tracking User ID Changes Use `TriggerAction` to react when the user ID changes: ```swift Swift theme={"dark"} var userIdTrigger: TriggerAction? func watchUserIdChanges() { userIdTrigger = Permutive.shared.triggerProvider?.actionUpdateForUserIdentity { userId in print("User ID changed to: \(userId)") } } // Release when done deinit { userIdTrigger = nil } ``` ```objectivec Objective-C theme={"dark"} @property (nonatomic, strong) PermutiveTriggerAction *userIdTrigger; - (void)watchUserIdChanges { self.userIdTrigger = [Permutive.shared.triggerProvider actionUpdateForUserIdentity:^(NSString *userId) { NSLog(@"User ID changed to: %@", userId); }]; } ``` ## Common Patterns ```swift Swift theme={"dark"} func onLoginSuccess(userId: String, email: String) { let emailHash = hashEmail(email) do { let aliases = [ Alias(tag: "email_sha256", identity: emailHash), Alias(tag: "internal_id", identity: userId, priority: 1) ] try Permutive.shared.setIdentities(aliases: aliases) } catch { print("Failed to set identity: \(error)") } } ``` ```objectivec Objective-C theme={"dark"} - (void)onLoginSuccessWithUserId:(NSString *)userId email:(NSString *)email { NSString *emailHash = [self hashEmail:email]; NSError *error = nil; PermutiveAlias *emailAlias = [[PermutiveAlias alloc] initWithTag:@"email_sha256" identity:emailHash]; PermutiveAlias *idAlias = [[PermutiveAlias alloc] initWithTag:@"internal_id" identity:userId priority:1]; [Permutive.shared setIdentitiesWithAliases:@[emailAlias, idAlias] error:&error]; } ``` ```swift theme={"dark"} import UIKit import Permutive_iOS func setVendorIdentity() { guard let idfv = UIDevice.current.identifierForVendor?.uuidString else { return } let alias = Alias(tag: "idfv", identity: idfv, priority: 2) try? Permutive.shared.setIdentities(aliases: [alias]) } ``` ```swift theme={"dark"} class UserManager { // User starts as guest (anonymous) func onAppLaunch() { // SDK automatically creates anonymous ID // Optionally set vendor identifier setVendorIdentity() } // User logs in or signs up func onUserAuthenticated(userId: String, email: String) { let emailHash = hashEmail(email) // Permutive merges guest data with authenticated profile try? Permutive.shared.setIdentities(aliases: [ Alias(tag: "email_sha256", identity: emailHash), Alias(tag: "internal_id", identity: userId, priority: 1) ]) } } ``` ## Expiry Aliases can expire automatically, useful for GDPR compliance, session identifiers, and temporary access tokens. ```swift theme={"dark"} // Never expire (default) Alias(tag: "email_sha256", identity: emailHash) // Expire in 30 days let thirtyDaysFromNow = Date().addingTimeInterval(86400 * 30) Alias(tag: "session_id", identity: sessionId, expiry: thirtyDaysFromNow) // Expire at distant future (effectively never) Alias(tag: "permanent_id", identity: id, expiry: Date.distantFuture) ``` ## tvOS Considerations **tvOS Note:** Identity management works identically on tvOS. App Tracking Transparency and IDFA are available on tvOS from version 14.5 onwards. ## Troubleshooting **Problem:** Setting identity doesn't merge user data across devices. **Solutions:** * Check network connectivity * Verify the alias has been used in other sessions/devices * Enable debug logging: `options.logModes = LogMode.all` * Look for identity-related logs in the console **Problem:** Same user appears as two different users. **Solution:** Use consistent alias tags and values. When a user logs in on multiple devices, use the same alias (e.g., hashed email). **Problem:** Alias with certain tags is ignored. **Solution:** Avoid reserved tags: `appnexus`, `amp`, `gigya`, `sailthru`, `aaid`. Use custom tags instead. ## Best Practices * Hash PII (especially email addresses) before setting as identity * Use meaningful tag names that describe the identifier type * Set priorities based on reliability and persistence * Use expiry dates for temporary or less reliable identifiers * Set identity as early as possible in the user journey * Use `identifierForVendor` as a fallback identifier * Send unhashed email addresses or phone numbers * Use reserved tag names * Use generic tag names like "id1", "id2" * Set identity multiple times unnecessarily * Skip priority assignment when using multiple aliases * Rely on IDFA as your primary identifier ## Related Documentation Apple advertising identifier integration Understanding user segments React to cohort changes Solutions to common issues # Event Tracking Source: https://docs.permutive.com/sdks/mobile/ios/features/event-tracking Track custom events directly with the Permutive SDK While `PageTracker` is the recommended approach for most tracking, you can also track custom events directly using the `track(event:properties:)` method. ## When to Use Direct Event Tracking Use direct event tracking for: * Events that don't fit the page view model * Background events (app state changes, push notifications) * One-off events without context * Events outside of a view lifecycle For view-based tracking with engagement time, scroll depth, and contextual cohorts, use [PageTracker](/sdks/mobile/ios/features/page-tracking) instead. ## Tracking Events ### Basic Event ```swift Swift theme={"dark"} do { try Permutive.shared.track(event: "AppLaunch") } catch { print("Failed to track event: \(error)") } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; [Permutive.shared trackWithEvent:@"AppLaunch" properties:nil error:&error]; if (error != nil) { NSLog(@"Failed to track event: %@", error); } ``` ### Event with Properties ```swift Swift theme={"dark"} do { let properties = try EventProperties([ "button_name": "subscribe", "position": "header", "is_premium": true ]) try Permutive.shared.track(event: "ButtonClick", properties: properties) } catch { print("Failed to track event: \(error)") } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"button_name": @"subscribe", @"position": @"header", @"is_premium": @YES } error:&error]; [Permutive.shared trackWithEvent:@"ButtonClick" properties:properties error:&error]; ``` ## Event Naming Rules Event names must follow these rules: * Only alphanumeric characters and underscores: `[a-zA-Z0-9_]` * Cannot start with a number * Case-sensitive ```swift theme={"dark"} "AppLaunch" // ✅ "button_click" // ✅ "VideoPlay2" // ✅ "user_subscription" // ✅ ``` ```swift theme={"dark"} "button-click" // ❌ Hyphen not allowed "2_event" // ❌ Cannot start with number "my event" // ❌ Spaces not allowed "événement" // ❌ Non-ASCII characters ``` ## Schema Validation Event properties **must match exactly** the schema defined in your Permutive dashboard. Mismatched properties cause event rejection. ### Enable Debug Logging ```swift theme={"dark"} options.logModes = LogMode.all ``` ### Schema Error Example When properties don't match the schema: ``` Permutive: [error] Encountered 1 event rejection! Permutive: [error] Error 1: A validation check carried out by the server did not succeed.(1007) Permutive: [error] Error 1: Schema validation failed with reason(s): [#: extraneous key [invalid_key] is not permitted] ``` ### Checking Events Were Accepted Successful events show: ``` Permutive: [info] Accepted: 1 / 1 ``` ## Common Event Types ### App Lifecycle Events ```swift Swift theme={"dark"} // App launch func applicationDidBecomeActive() { try? Permutive.shared.track( event: "AppActive", properties: try? EventProperties([ "launch_type": isFirstLaunch ? "fresh" : "resume" ]) ) } // App background func applicationWillResignActive() { try? Permutive.shared.track(event: "AppBackground") } ``` ```objectivec Objective-C theme={"dark"} // App launch - (void)applicationDidBecomeActive:(UIApplication *)application { NSError *error = nil; PermutiveEventProperties *props = [[PermutiveEventProperties alloc] init:@{@"launch_type": self.isFirstLaunch ? @"fresh" : @"resume"} error:&error]; [Permutive.shared trackWithEvent:@"AppActive" properties:props error:&error]; } ``` ### User Action Events ```swift Swift theme={"dark"} // Button click func onSubscribeButtonTapped() { try? Permutive.shared.track( event: "SubscribeClick", properties: try? EventProperties([ "plan": "premium", "source": "paywall" ]) ) } // Search func onSearch(query: String, resultCount: Int) { try? Permutive.shared.track( event: "Search", properties: try? EventProperties([ "query_length": query.count, "result_count": resultCount, "has_results": resultCount > 0 ]) ) } ``` ```objectivec Objective-C theme={"dark"} // Button click - (void)onSubscribeButtonTapped { NSError *error = nil; PermutiveEventProperties *props = [[PermutiveEventProperties alloc] init:@{@"plan": @"premium", @"source": @"paywall"} error:&error]; [Permutive.shared trackWithEvent:@"SubscribeClick" properties:props error:&error]; } ``` ### Push Notification Events ```swift theme={"dark"} func userNotificationCenter( _ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse ) { let userInfo = response.notification.request.content.userInfo try? Permutive.shared.track( event: "PushNotificationOpen", properties: try? EventProperties([ "campaign_id": userInfo["campaign_id"] as? String ?? "unknown", "action": response.actionIdentifier ]) ) } ``` ### Purchase Events ```swift Swift theme={"dark"} func onPurchaseComplete(product: SKProduct, transaction: SKPaymentTransaction) { try? Permutive.shared.track( event: "Purchase", properties: try? EventProperties([ "product_id": product.productIdentifier, "price": product.price.doubleValue, "currency": product.priceLocale.currencyCode ?? "USD", "transaction_id": transaction.transactionIdentifier ?? "" ]) ) } ``` ```objectivec Objective-C theme={"dark"} - (void)onPurchaseCompleteWithProduct:(SKProduct *)product transaction:(SKPaymentTransaction *)transaction { NSError *error = nil; PermutiveEventProperties *props = [[PermutiveEventProperties alloc] init:@{ @"product_id": product.productIdentifier, @"price": product.price, @"currency": product.priceLocale.currencyCode ?: @"USD", @"transaction_id": transaction.transactionIdentifier ?: @"" } error:&error]; [Permutive.shared trackWithEvent:@"Purchase" properties:props error:&error]; } ``` ## Event Enrichment Add server-side enrichment to events: ```swift theme={"dark"} let properties = try EventProperties([ "geo_info": EventProperties.geoInfoValue, "isp_info": EventProperties.ispInfoValue, "form_id": "contact_form" ]) try Permutive.shared.track(event: "FormSubmit", properties: properties) ``` See [Event Properties](/sdks/mobile/ios/core-concepts/event-properties) for all enrichment options. ## Batching and Delivery Events are: * Queued locally when tracked * Sent in batches to reduce network overhead * Persisted to disk if the app closes before sending * Retried automatically on network failure You don't need to manage batching - it's handled automatically. ## Error Handling ```swift Swift theme={"dark"} func trackEvent(name: String, properties: [String: Any]) { do { let eventProperties = try EventProperties(properties) try Permutive.shared.track(event: name, properties: eventProperties) } catch let error as NSError { // Log but don't crash - tracking failures shouldn't break app print("Event tracking failed: \(error.localizedDescription)") // Optionally report to error tracking // Crashlytics.log("Permutive track error: \(error)") } } ``` ```objectivec Objective-C theme={"dark"} - (void)trackEvent:(NSString *)name properties:(NSDictionary *)properties { NSError *error = nil; PermutiveEventProperties *eventProps = [[PermutiveEventProperties alloc] init:properties error:&error]; if (error != nil) { NSLog(@"Failed to create properties: %@", error); return; } [Permutive.shared trackWithEvent:name properties:eventProps error:&error]; if (error != nil) { NSLog(@"Event tracking failed: %@", error); } } ``` ## Best Practices * Use descriptive, consistent event names * Match your dashboard schema exactly * Test events with debug logging enabled * Handle errors gracefully * Use PageTracker for view-based tracking * Keep properties minimal and relevant * Don't include PII in event properties * Don't track too many fine-grained events * Don't use dynamic event names not in your schema * Don't block the UI waiting for tracking * Don't track sensitive data (passwords, tokens) ## Troubleshooting **Problem:** Tracked events don't show up. **Solutions:** * Enable debug logging and look for `Accepted: X / X` * Check for schema validation errors in logs * Wait up to 5 minutes for processing * Verify you're in the correct workspace **Problem:** Creating EventProperties throws an error. **Solutions:** * Verify all values are supported types * Check for unsupported custom objects * Ensure arrays contain only supported types **Problem:** Events sent but rejected by server. **Solutions:** * Check event name matches schema exactly * Verify property names and types * Remove properties not in the schema * Check for typos ## Related Documentation View-based tracking with PageTracker Structuring event metadata Track video content Common problems and solutions # Page Tracking Source: https://docs.permutive.com/sdks/mobile/ios/features/page-tracking Track page views and user engagement with PageTracker `PageTracker` is the recommended approach for tracking user interactions in your iOS and tvOS apps. It automatically generates `Pageview` events, measures engagement time, and enables contextual cohorts when URLs are provided. ## Overview `PageTracker` provides: * **Automatic `Pageview` events** on first resume * **Engagement time tracking** between resume and pause * **`PageViewComplete` events** when stopped * **Contextual cohort generation** when URLs are provided * **Linked event tracking** with consistent view IDs **Only one PageTracker (or MediaTracker) can be active at a time.** Creating a new tracker automatically stops any existing one. ## Creating a PageTracker ```swift Swift theme={"dark"} import Permutive_iOS class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() // Create event properties (optional) let properties = try? EventProperties([ "category": "sports", "subcategory": "football", "author": "Jane Smith", "premium": true ]) // Create context with page information let context = Context( title: "Match Preview: Team A vs Team B", url: URL(string: "https://example.com/sports/match-preview"), referrer: URL(string: "https://example.com/sports") ) // Create the PageTracker pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) } } ``` ```objectivec Objective-C theme={"dark"} #import "ArticleViewController.h" @import Permutive_iOS; @interface ArticleViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; // Create event properties NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{ @"category": @"sports", @"subcategory": @"football", @"author": @"Jane Smith", @"premium": @YES } error:&error]; // Create context PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Match Preview: Team A vs Team B" url:[NSURL URLWithString:@"https://example.com/sports/match-preview"] referrer:[NSURL URLWithString:@"https://example.com/sports"]]; // Create the PageTracker self.pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; } @end ``` ## PageTracker Lifecycle ### State Diagram ``` ┌──────────────────────────────────────────────────────────────┐ │ │ │ Created ──► resume() ──► Running ──► pause() ──► Paused │ │ │ │ │ │ │ │ │ │ ▼ ▼ │ │ stop() ◄──────────────────┘ │ │ │ │ │ ▼ │ │ Stopped │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ### Lifecycle Methods | Method | Effect | Events Generated | | ---------- | ------------------------- | ---------------------------- | | `resume()` | Starts/resumes tracking | `Pageview` (first call only) | | `pause()` | Pauses engagement timer | None | | `stop()` | Ends tracking permanently | `PageViewComplete` | ### UIViewController Integration ```swift Swift theme={"dark"} class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() let context = Context( title: "Article Title", url: URL(string: "https://example.com/article"), referrer: nil ) pageTracker = try? Permutive.shared.createPageTracker( properties: nil, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) // Start or resume tracking try? pageTracker?.resume() } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) // Pause when view is not visible pageTracker?.pause() } deinit { // Stop tracking when view is deallocated pageTracker?.stop() } } ``` ```objectivec Objective-C theme={"dark"} @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Article Title" url:[NSURL URLWithString:@"https://example.com/article"] referrer:nil]; self.pageTracker = [Permutive.shared createPageTrackerWithProperties:nil context:context error:nil]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.pageTracker pause]; } - (void)dealloc { [self.pageTracker stop]; } @end ``` ## SwiftUI Integration For SwiftUI, use `onAppear` and `onDisappear` modifiers: ```swift theme={"dark"} import SwiftUI import Permutive_iOS struct ArticleView: View { let article: Article @StateObject private var tracker = PageTrackerWrapper() var body: some View { ScrollView { ArticleContent(article: article) } .onAppear { tracker.start( title: article.title, url: URL(string: article.url) ) } .onDisappear { tracker.stop() } } } class PageTrackerWrapper: ObservableObject { private var pageTracker: PageTrackerProtocol? func start(title: String, url: URL?) { let context = Context(title: title, url: url, referrer: nil) pageTracker = try? Permutive.shared.createPageTracker( properties: nil, context: context ) try? pageTracker?.resume() } func stop() { pageTracker?.stop() pageTracker = nil } } ``` ## Tracking Events Track additional events linked to the current page view: ```swift Swift theme={"dark"} // Track a link click try? pageTracker?.track( event: "LinkClick", properties: try? EventProperties([ "link_url": "https://example.com/related", "link_text": "Read More" ]) ) // Track a form submission try? pageTracker?.track( event: "FormSubmit", properties: try? EventProperties([ "form_id": "newsletter_signup", "email_provided": true ]) ) // Track without properties try? pageTracker?.track(event: "ShareButton", properties: nil) ``` ```objectivec Objective-C theme={"dark"} // Track a link click NSError *error = nil; PermutiveEventProperties *linkProps = [[PermutiveEventProperties alloc] init:@{@"link_url": @"https://example.com/related", @"link_text": @"Read More"} error:&error]; [self.pageTracker trackWithEvent:@"LinkClick" properties:linkProps error:&error]; // Track without properties [self.pageTracker trackWithEvent:@"ShareButton" properties:nil error:&error]; ``` Events tracked via `PageTracker.track()` include the same Context and view ID as the `Pageview` event, enabling linked analysis. ## Engagement Tracking ### Scroll Depth Track how much content users have viewed: ```swift Swift theme={"dark"} class ArticleViewController: UIViewController, UIScrollViewDelegate { private var pageTracker: PageTrackerProtocol? @IBOutlet weak var scrollView: UIScrollView! override func viewDidLoad() { super.viewDidLoad() scrollView.delegate = self // Setup pageTracker... } func scrollViewDidScroll(_ scrollView: UIScrollView) { let contentHeight = scrollView.contentSize.height - scrollView.bounds.height guard contentHeight > 0 else { return } let percentage = Float(scrollView.contentOffset.y / contentHeight) let clampedPercentage = min(max(percentage, 0), 1) pageTracker?.updateViewed(percentage: clampedPercentage) } } ``` ```objectivec Objective-C theme={"dark"} - (void)scrollViewDidScroll:(UIScrollView *)scrollView { CGFloat contentHeight = scrollView.contentSize.height - scrollView.bounds.size.height; if (contentHeight <= 0) return; float percentage = scrollView.contentOffset.y / contentHeight; percentage = MIN(MAX(percentage, 0), 1); [self.pageTracker updateViewedWithPercentage:percentage]; } ``` ### Engagement Time Engagement time is automatically tracked: * Timer starts when `resume()` is called * Timer pauses when `pause()` is called * Total engagement time sent with `PageViewComplete` event ## Context Object The `Context` object provides page metadata: | Property | Type | Description | | ---------- | -------- | ------------------------------------- | | `title` | `String` | Page title | | `url` | `URL?` | Page URL (enables contextual cohorts) | | `referrer` | `URL?` | Referring page URL | ```swift Swift theme={"dark"} let context = Context( title: "Article: iOS Development", url: URL(string: "https://example.com/ios-development"), referrer: URL(string: "https://example.com/tutorials") ) ``` ```objectivec Objective-C theme={"dark"} PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Article: iOS Development" url:[NSURL URLWithString:@"https://example.com/ios-development"] referrer:[NSURL URLWithString:@"https://example.com/tutorials"]]; ``` The `domain` is automatically inferred from the `url` if set. Always provide URLs to enable contextual cohort generation. ## Background Handling The SDK automatically handles app backgrounding: ```swift theme={"dark"} // When app enters background: // - Active PageTracker is automatically stopped // - PageViewComplete event is sent // When resuming, create a new PageTracker if needed func applicationWillEnterForeground() { if shouldResumeTracking { createAndResumePageTracker() } } ``` ## tvOS Considerations **tvOS Note:** PageTracker works identically on tvOS. Use focus-based navigation events instead of touch-based scrolling for engagement tracking. ```swift theme={"dark"} // tvOS focus tracking example func didUpdateFocus(in context: UIFocusUpdateContext, with coordinator: UIFocusAnimationCoordinator) { // Track focus changes as navigation events if let focusedView = context.nextFocusedView { try? pageTracker?.track( event: "FocusChange", properties: try? EventProperties([ "focused_element": String(describing: type(of: focusedView)) ]) ) } } ``` ## Error Handling ```swift Swift theme={"dark"} do { let pageTracker = try Permutive.shared.createPageTracker( properties: properties, context: context ) try pageTracker.resume() } catch { print("PageTracker error: \(error)") // Handle error - tracking will be skipped } ``` ```objectivec Objective-C theme={"dark"} NSError *error = nil; NSObject *pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; if (error != nil) { NSLog(@"PageTracker creation error: %@", error); return; } [pageTracker resumeAndReturnError:&error]; if (error != nil) { NSLog(@"PageTracker resume error: %@", error); } ``` ## Best Practices * Create PageTracker in `viewDidLoad` * Call `resume()` in `viewDidAppear` * Call `pause()` in `viewDidDisappear` * Call `stop()` in `deinit` * Always provide URLs for contextual targeting * Track meaningful events with descriptive names * Update scroll percentage as user scrolls * Don't create multiple PageTrackers simultaneously * Don't call `resume()` after `stop()` * Don't forget to call `stop()` when done * Don't track too many fine-grained events * Don't include PII in event properties ## Troubleshooting **Problem:** No Pageview event in logs. **Solutions:** * Ensure `resume()` is called after creating the PageTracker * Check that SDK is initialized before creating PageTracker * Verify no errors when creating PageTracker * Enable debug logging: `options.logModes = LogMode.all` **Problem:** PageTracker stops when navigating. **Cause:** Creating a new PageTracker stops any existing one. **Solution:** This is expected behavior. Only one tracker can be active. Stop the previous tracker explicitly if needed, or let the new one replace it. **Problem:** Events tracked via PageTracker are rejected. **Solutions:** * Check event names match your schema * Verify property names and types * Enable debug logging to see schema errors ## Related Documentation Track custom events Content-based targeting Ad targeting with PageTracker Structuring event data # Triggers Provider Source: https://docs.permutive.com/sdks/mobile/ios/features/triggers-provider React to cohort changes and user identity updates in real-time `TriggerProvider` enables reactive updates when users enter or exit cohorts, allowing your app to respond to segment changes in real-time. ## Overview `TriggerProvider` provides: * **Real-time cohort change notifications** * **Immediate callback when users enter/exit cohorts** * **Query-based triggers** for complex conditions * **User identity change monitoring** Use `TriggerProvider` instead of polling `cohorts` or `activations` for reactive behavior. ## Accessing TriggerProvider ```swift Swift theme={"dark"} let triggerProvider = Permutive.shared.triggerProvider ``` ```objectivec Objective-C theme={"dark"} id triggerProvider = Permutive.shared.triggerProvider; ``` ## Cohort Membership Triggers Watch for changes in cohort membership: ```swift Swift theme={"dark"} import Permutive_iOS class FeatureController { private var premiumTrigger: TriggerAction? func watchPremiumStatus() { premiumTrigger = Permutive.shared.triggerProvider?.action( boolFor: ["premium_subscriber"], action: { cohortId, isInCohort in print("Cohort '\(cohortId)' membership: \(isInCohort)") if isInCohort { self.enablePremiumFeatures() } else { self.disablePremiumFeatures() } } ) } private func enablePremiumFeatures() { // Show premium content } private func disablePremiumFeatures() { // Hide premium content } deinit { // Release trigger to stop watching premiumTrigger = nil } } ``` ```objectivec Objective-C theme={"dark"} @interface FeatureController () @property (nonatomic, strong) PermutiveTriggerAction *premiumTrigger; @end @implementation FeatureController - (void)watchPremiumStatus { NSSet *cohorts = [NSSet setWithObject:@"premium_subscriber"]; self.premiumTrigger = [Permutive.shared.triggerProvider actionWithBoolFor:cohorts action:^(NSString *cohortId, BOOL isInCohort) { NSLog(@"Cohort '%@' membership: %@", cohortId, isInCohort ? @"YES" : @"NO"); if (isInCohort) { [self enablePremiumFeatures]; } else { [self disablePremiumFeatures]; } }]; } - (void)dealloc { // Release trigger self.premiumTrigger = nil; } @end ``` ### Watching Multiple Cohorts ```swift Swift theme={"dark"} class ContentPersonalizer { private var contentTrigger: TriggerAction? func watchUserInterests() { contentTrigger = Permutive.shared.triggerProvider?.action( boolFor: ["sports_enthusiast", "tech_reader", "news_follower"], action: { cohortId, isInCohort in if isInCohort { switch cohortId { case "sports_enthusiast": self.boostSportsContent() case "tech_reader": self.boostTechContent() case "news_follower": self.boostNewsContent() default: break } } } ) } } ``` ```objectivec Objective-C theme={"dark"} - (void)watchUserInterests { NSSet *cohorts = [NSSet setWithObjects: @"sports_enthusiast", @"tech_reader", @"news_follower", nil]; self.contentTrigger = [Permutive.shared.triggerProvider actionWithBoolFor:cohorts action:^(NSString *cohortId, BOOL isInCohort) { if (isInCohort) { if ([cohortId isEqualToString:@"sports_enthusiast"]) { [self boostSportsContent]; } else if ([cohortId isEqualToString:@"tech_reader"]) { [self boostTechContent]; } else if ([cohortId isEqualToString:@"news_follower"]) { [self boostNewsContent]; } } }]; } ``` ## Query Triggers For more complex data, use query triggers that return dictionaries or integers: ### Dictionary Queries ```swift Swift theme={"dark"} class AnalyticsController { private var queryTrigger: TriggerAction? func watchComplexQueries() { queryTrigger = Permutive.shared.triggerProvider?.action( dictionaryFor: ["user_profile_query", "engagement_metrics"], action: { queryId, result in print("Query '\(queryId)' returned: \(result)") if queryId == "user_profile_query", let preferences = result["preferences"] as? [String: Any] { self.applyUserPreferences(preferences) } } ) } } ``` ```objectivec Objective-C theme={"dark"} - (void)watchComplexQueries { NSSet *queries = [NSSet setWithObjects:@"user_profile_query", @"engagement_metrics", nil]; self.queryTrigger = [Permutive.shared.triggerProvider actionWithDictionaryFor:queries action:^(NSString *queryId, NSDictionary, NSObject *> *result) { NSLog(@"Query '%@' returned: %@", queryId, result); if ([queryId isEqualToString:@"user_profile_query"]) { NSDictionary *preferences = result[@"preferences"]; if (preferences) { [self applyUserPreferences:preferences]; } } }]; } ``` ### Integer Queries ```swift Swift theme={"dark"} class ScoreController { private var scoreTrigger: TriggerAction? func watchEngagementScore() { scoreTrigger = Permutive.shared.triggerProvider?.action( intFor: ["engagement_score"], action: { queryId, score in print("Engagement score: \(score)") self.updateUIForScore(score) } ) } private func updateUIForScore(_ score: Int) { // Adjust UI based on engagement level } } ``` ```objectivec Objective-C theme={"dark"} - (void)watchEngagementScore { NSSet *queries = [NSSet setWithObject:@"engagement_score"]; self.scoreTrigger = [Permutive.shared.triggerProvider actionWithIntFor:queries action:^(NSString *queryId, NSInteger score) { NSLog(@"Engagement score: %ld", (long)score); [self updateUIForScore:score]; }]; } ``` ## User ID Triggers Monitor changes to the user identity: ```swift Swift theme={"dark"} class SessionController { private var userIdTrigger: TriggerAction? func watchUserIdentityChanges() { userIdTrigger = Permutive.shared.triggerProvider?.actionUpdateForUserIdentity { userId in print("User identity changed to: \(userId)") // Update analytics with new user ID Analytics.setUserId(userId) // Refresh user-specific data self.refreshUserData() } } deinit { userIdTrigger = nil } } ``` ```objectivec Objective-C theme={"dark"} @interface SessionController () @property (nonatomic, strong) PermutiveTriggerAction *userIdTrigger; @end @implementation SessionController - (void)watchUserIdentityChanges { self.userIdTrigger = [Permutive.shared.triggerProvider actionUpdateForUserIdentity:^(NSString *userId) { NSLog(@"User identity changed to: %@", userId); [Analytics setUserId:userId]; [self refreshUserData]; }]; } - (void)dealloc { self.userIdTrigger = nil; } @end ``` ## TriggerAction Lifecycle You must maintain a strong reference to `TriggerAction` objects. Releasing the reference stops the trigger. ### Keeping Triggers Active ```swift theme={"dark"} class TriggerManager { // Store triggers as instance properties private var cohortTrigger: TriggerAction? private var userIdTrigger: TriggerAction? func setupTriggers() { cohortTrigger = Permutive.shared.triggerProvider?.action( boolFor: ["cohort"], action: { _, _ in } ) userIdTrigger = Permutive.shared.triggerProvider?.actionUpdateForUserIdentity { _ in } } func stopWatching() { // Explicitly release triggers cohortTrigger = nil userIdTrigger = nil } deinit { // Automatically released when controller is deallocated } } ``` ## UIViewController Integration ```swift Swift theme={"dark"} class PersonalizedViewController: UIViewController { private var cohortTrigger: TriggerAction? override func viewDidLoad() { super.viewDidLoad() // Start watching cohorts cohortTrigger = Permutive.shared.triggerProvider?.action( boolFor: ["premium_user", "new_user"], action: { [weak self] cohortId, isInCohort in DispatchQueue.main.async { self?.handleCohortChange(cohortId: cohortId, isInCohort: isInCohort) } } ) } private func handleCohortChange(cohortId: String, isInCohort: Bool) { switch cohortId { case "premium_user": updatePremiumUI(enabled: isInCohort) case "new_user": showOnboarding(isNew: isInCohort) default: break } } deinit { cohortTrigger = nil } } ``` ```objectivec Objective-C theme={"dark"} @interface PersonalizedViewController () @property (nonatomic, strong) PermutiveTriggerAction *cohortTrigger; @end @implementation PersonalizedViewController - (void)viewDidLoad { [super viewDidLoad]; NSSet *cohorts = [NSSet setWithObjects:@"premium_user", @"new_user", nil]; __weak typeof(self) weakSelf = self; self.cohortTrigger = [Permutive.shared.triggerProvider actionWithBoolFor:cohorts action:^(NSString *cohortId, BOOL isInCohort) { dispatch_async(dispatch_get_main_queue(), ^{ [weakSelf handleCohortChange:cohortId isInCohort:isInCohort]; }); }]; } - (void)handleCohortChange:(NSString *)cohortId isInCohort:(BOOL)isInCohort { if ([cohortId isEqualToString:@"premium_user"]) { [self updatePremiumUI:isInCohort]; } else if ([cohortId isEqualToString:@"new_user"]) { [self showOnboarding:isInCohort]; } } - (void)dealloc { self.cohortTrigger = nil; } @end ``` ## SwiftUI Integration ```swift theme={"dark"} import SwiftUI import Permutive_iOS struct PersonalizedView: View { @StateObject private var triggerManager = TriggerManager() var body: some View { VStack { if triggerManager.isPremium { PremiumContentView() } else { StandardContentView() } } .onAppear { triggerManager.startWatching() } .onDisappear { triggerManager.stopWatching() } } } class TriggerManager: ObservableObject { @Published var isPremium = false private var trigger: TriggerAction? func startWatching() { trigger = Permutive.shared.triggerProvider?.action( boolFor: ["premium_subscriber"], action: { [weak self] _, isInCohort in DispatchQueue.main.async { self?.isPremium = isInCohort } } ) } func stopWatching() { trigger = nil } } ``` ## tvOS Considerations **tvOS Note:** TriggerProvider works identically on tvOS. Use it to update UI elements based on cohort membership in your focus-based navigation. ## Best Practices * Store TriggerAction references as instance properties * Use `[weak self]` in closures to avoid retain cycles * Dispatch UI updates to main thread * Release triggers when no longer needed * Group related cohorts in a single trigger * Don't create triggers without storing the reference * Don't create excessive numbers of triggers * Don't perform heavy work in trigger callbacks * Don't assume immediate callback on creation * Don't forget to handle both enter and exit cases ## Troubleshooting **Problem:** No callbacks when cohort membership changes. **Solutions:** * Verify you're storing a strong reference to TriggerAction * Check that cohort IDs match your dashboard * Enable debug logging to see cohort updates * Ensure SDK is initialized before creating triggers **Problem:** Trigger worked initially but stopped. **Cause:** TriggerAction reference was released. **Solution:** Store TriggerAction as an instance property, not a local variable. **Problem:** Callback fires but UI doesn't change. **Solution:** Dispatch UI updates to main thread: ```swift theme={"dark"} DispatchQueue.main.async { self.updateUI() } ``` ## Related Documentation Understanding user segments User identity tracking Trigger cohort qualification Common problems and solutions # Video Ad Tracking Source: https://docs.permutive.com/sdks/mobile/ios/features/video-ad-tracking Emit standard video ad events from iOS / tvOS using Permutive.shared.track() Track video ad events to measure ad engagement and enable ad-based cohort qualification. ## Overview **iOS / tvOS does not have a native ad tracker.** Unlike Android's `VideoAdTracker`, iOS does not provide a typed API for ad tracking. Emit the standard `VideoAdView`, `VideoAdCompletion`, and `VideoAdClicked` events using `Permutive.shared.track(event:properties:)` with properties nested under an `ad` parent per the [canonical schema](/sdks/ctv/video-tracking#ad-event-properties). The three schema events for ad tracking are: | Event | When to emit | | ----------------------- | ------------------- | | **`VideoAdView`** | Ad playback begins | | **`VideoAdCompletion`** | Ad finishes playing | | **`VideoAdClicked`** | User clicks the ad | All three emit `ad.*` properties (and optionally a `video.*` parent for the content the ad ran against). See the schema reference below. *** ## Tracking Ad Events ### VideoAdView Emit when the ad begins playback: ```swift theme={"dark"} import Permutive_iOS func trackAdView(ad: Ad) { try? Permutive.shared.track( event: "VideoAdView", properties: try? EventProperties([ "ad": [ "title": ad.title, "duration": ad.durationInSeconds, "muted": ad.isMuted, "campaign_id": ad.campaignId, "creative_id": ad.creativeId ] ]) ) } ``` ### VideoAdCompletion Emit when the ad finishes: ```swift theme={"dark"} func trackAdCompletion(ad: Ad) { try? Permutive.shared.track( event: "VideoAdCompletion", properties: try? EventProperties([ "ad": [ "title": ad.title, "duration": ad.durationInSeconds, "campaign_id": ad.campaignId, "creative_id": ad.creativeId ] ]) ) } ``` ### VideoAdClicked Emit when the user clicks through: ```swift theme={"dark"} func trackAdClicked(ad: Ad) { try? Permutive.shared.track( event: "VideoAdClicked", properties: try? EventProperties([ "ad": [ "title": ad.title, "campaign_id": ad.campaignId, "creative_id": ad.creativeId ] ]) ) } ``` **Skipped or errored ads:** the schema defines only `VideoAdView`, `VideoAdCompletion`, and `VideoAdClicked`. Treat a skip as no completion event (no `VideoAdCompletion`). If you need to capture skip/error signals for your own analytics, use a custom event name and document it in your workspace schema. *** ## Combining with Content Tracking Pause the content video tracker during ad breaks so engagement time isn't counted twice: ```swift theme={"dark"} class VideoPlayerController { private var mediaTracker: (NSObject & MediaTrackerProtocol)? private var isPlayingAd = false // Content tracking func onContentPlay() { guard !isPlayingAd else { return } mediaTracker?.play() } func onContentPause() { guard !isPlayingAd else { return } mediaTracker?.pause() } // Ad tracking func onAdBreakStarted() { isPlayingAd = true mediaTracker?.pause() // Pause content engagement during ads } func onAdBreakEnded() { isPlayingAd = false // Content resumes via onContentPlay() } func onAdStarted(_ ad: Ad) { try? Permutive.shared.track( event: "VideoAdView", properties: try? EventProperties([ "ad": [ "title": ad.title, "duration": ad.durationInSeconds, "campaign_id": ad.campaignId, "creative_id": ad.creativeId ] ]) ) } func onAdCompleted(_ ad: Ad) { try? Permutive.shared.track( event: "VideoAdCompletion", properties: try? EventProperties([ "ad": [ "title": ad.title, "campaign_id": ad.campaignId, "creative_id": ad.creativeId ] ]) ) } } ``` *** ## Google IMA Integration Hook `IMAAdsManagerDelegate` events to emit Permutive ad events: ```swift theme={"dark"} import GoogleInteractiveMediaAds import Permutive_iOS class VideoPlayerViewController: UIViewController, IMAAdsManagerDelegate { func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) { guard let imaAd = event.ad else { return } switch event.type { case .STARTED: emitAdView(imaAd) case .COMPLETE: emitAdCompletion(imaAd) case .CLICKED: emitAdClicked(imaAd) default: break } } private func emitAdView(_ ad: IMAAd) { try? Permutive.shared.track( event: "VideoAdView", properties: try? EventProperties([ "ad": [ "title": ad.adTitle, "duration": Int(ad.duration), "campaign_id": ad.adId, "creative_id": ad.creativeID ?? "" ] ]) ) } private func emitAdCompletion(_ ad: IMAAd) { try? Permutive.shared.track( event: "VideoAdCompletion", properties: try? EventProperties([ "ad": [ "title": ad.adTitle, "campaign_id": ad.adId, "creative_id": ad.creativeID ?? "" ] ]) ) } private func emitAdClicked(_ ad: IMAAd) { try? Permutive.shared.track( event: "VideoAdClicked", properties: try? EventProperties([ "ad": [ "title": ad.adTitle, "campaign_id": ad.adId, "creative_id": ad.creativeID ?? "" ] ]) ) } } ``` IMA's `adId` is the line-item / ad reference. Map it to whichever Permutive schema field reflects your taxonomy (`campaign_id` shown here, but use `creative_id` if that's a closer match). *** ## Schema Reference The canonical schema for ad events is defined in [CTV Video Tracking](/sdks/ctv/video-tracking#ad-event-properties). Summary: | Property | Type | Description | | ---------------- | ------ | ------------------------ | | `ad.title` | String | Ad title | | `ad.duration` | Int | Ad duration in seconds | | `ad.muted` | Bool | Whether the ad was muted | | `ad.campaign_id` | String | Campaign identifier | | `ad.creative_id` | String | Creative identifier | For `VideoAdCompletion`, the SDK does not auto-aggregate engagement on iOS (no native ad tracker means no `aggregations.VideoAdEngagement.*` enrichment) — emit only the `ad.*` properties. Ensure property names match your Permutive workspace schema. Mismatched properties are rejected. *** ## tvOS Considerations **tvOS Note:** Ad tracking on tvOS uses the same `Permutive.shared.track(event:properties:)` API. Use it from your TVMLKit or UIKit video player. *** ## Best Practices * Emit `VideoAdView` only when the ad is actually visible / playing * Nest all ad properties under an `ad` parent (e.g., `ad.title`, not flat `ad_title`) * Use the canonical event names — `VideoAdView`, `VideoAdCompletion`, `VideoAdClicked` * Pause the content `MediaTracker` during ad breaks so content engagement isn't inflated * Pass duration in seconds (Int), not milliseconds * Don't invent event names like `VideoAdImpression` or `VideoAdSkipped` unless they're configured in your workspace schema * Don't flatten ad properties at the top level (the schema requires `ad.*` nesting) * Don't track an ad impression before the ad actually starts playing * Don't include PII in ad properties *** ## Troubleshooting **Problem:** Ad events do not show in the Permutive dashboard. **Solutions:** * Confirm `Permutive.configure(...)` ran before `track(...)` is called * Verify event names match: `VideoAdView`, `VideoAdCompletion`, `VideoAdClicked` * Check that `ad.*` property nesting matches your workspace schema * Enable debug logging and watch for schema validation errors **Problem:** Logs show events being rejected. **Solutions:** * Ensure all properties are nested under `ad` (not at the top level) * Check property types — `duration` must be Int, `muted` must be Bool * Verify the event name spelling exactly matches the schema **Problem:** Permutive targeting does not appear on GAM ad requests. **Solutions:** * Call `googleCustomTargeting(adTargetable:)` before the ad request * Pass an active `MediaTracker` or `PageTracker` as `adTargetable` so targeting reflects the current session * Confirm the targeting dictionary is applied to the `GAMRequest` *** ## Related Documentation Track video content Canonical event and property reference GAM integration Custom event tracking # Video Tracking Source: https://docs.permutive.com/sdks/mobile/ios/features/video-tracking Track video playback, engagement, and completion metrics The `MediaTracker` API allows you to track video content events with Permutive. Use this for tracking video playback, engagement, and completion metrics. **Connected TV Integration** Video event tracking described below is available once the connected TV integration has been enabled. Please contact your Customer Success Manager (CSM) to enable this feature. ## Overview `MediaTracker` provides comprehensive video tracking capabilities: * **Automatic lifecycle tracking** - Tracks Videoview and VideoCompletion events * **Engagement metrics** - Measures time spent watching and completion percentage * **Custom events** - Track custom video-related events * **Rich metadata** - Support for extensive video properties *** ## Video Events MediaTracker automatically tracks two event types: ### 1. Videoview Event Tracked when MediaTracker is created: ``` Event: Videoview Properties: - [your custom properties] - [standard video properties] ``` ### 2. VideoCompletion Event Tracked when video is stopped: ``` Event: VideoCompletion Properties: - aggregations.VideoEngagement.engaged_time: Total time spent watching (seconds) - aggregations.VideoEngagement.completion: Percentage of video viewed (0.0 - 1.0) - [your custom properties] - [standard video properties] ``` > 📘 Note > > The `aggregations.VideoEngagement.completion` property requires a known duration to be set. Pass `duration` (in seconds) when calling `createVideoTracker(...)`. *** ## Basic Usage ### Creating a Video Tracker Create a video tracker when playback begins. The iOS SDK does not auto-nest publisher properties under `video` like Android does — hand-build the nested `EventProperties` dictionary so the emitted event matches the canonical schema (`video.title`, `video.content_type`, …). See [CTV Video Tracking](/sdks/ctv/video-tracking#video-event-schema) for the full schema. ```swift Swift theme={"dark"} import Permutive_iOS import AVKit class VideoPlayerViewController: UIViewController { private var mediaTracker: (NSObject & MediaTrackerProtocol)? private var player: AVPlayer! override func viewDidLoad() { super.viewDidLoad() let videoProps = try? EventProperties([ "video": [ "title": "Sample Video", "genre": ["Documentary"], "content_type": ["Education"], "runtime": 120 ] ]) // `duration` is a TimeInterval (seconds), not milliseconds. mediaTracker = try? Permutive.shared.createVideoTracker( duration: 120, // 2 minutes properties: videoProps ) } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) mediaTracker?.stop() // Important: Always stop to send VideoCompletion } } ``` ```objectivec Objective-C theme={"dark"} #import "VideoPlayerViewController.h" @import Permutive_iOS; @import AVKit; @interface VideoPlayerViewController () @property (nonatomic, strong) NSObject *mediaTracker; @property (nonatomic, strong) AVPlayer *player; @end @implementation VideoPlayerViewController - (void)viewDidLoad { [super viewDidLoad]; NSError *error = nil; PermutiveEventProperties *videoProps = [[PermutiveEventProperties alloc] init:@{ @"video": @{ @"title": @"Sample Video", @"genre": @[@"Documentary"], @"content_type": @[@"Education"], @"runtime": @120 } } error:&error]; // duration is in seconds. self.mediaTracker = [Permutive.shared createVideoTrackerWithDuration:120 properties:videoProps context:nil error:&error]; } - (void)viewWillDisappear:(BOOL)animated { [super viewWillDisappear:animated]; [self.mediaTracker stop]; // Important: Always stop to send VideoCompletion } @end ``` *** ## MediaTracker Lifecycle ### Expected Usage Flow 1. **Create** MediaTracker instance with properties 2. **Call** `play()` when playback begins 3. **Track buffering** with `pause()` / `play()` 4. **Track scrubbing** with `play(position)` 5. **Call** `stop()` when playback completes > ⚠️ Single Instance Limitation > > Only a single instance of `PageTracker` or `MediaTracker` is available at any time. Creating a new tracker automatically stops any existing one. ### Playback Control Methods #### play() Call when video starts playing: ```swift theme={"dark"} mediaTracker?.play() ``` #### play(position:) Call when playback position changes (e.g., seeking). Position is a `TimeInterval` in seconds. ```swift theme={"dark"} mediaTracker?.play(position: 30) // Seek to 30 seconds ``` #### pause() Call when video is paused or buffering: ```swift theme={"dark"} mediaTracker?.pause() ``` #### stop() Call when video playback completes or user exits: ```swift theme={"dark"} mediaTracker?.stop() // Sends VideoCompletion event ``` #### set(duration:) Call to update the video duration if it wasn't known when the tracker was created: ```swift theme={"dark"} mediaTracker?.set(duration: 240) // 4 minutes ``` > ⚠️ Important: Always Call stop() > > Failing to call `stop()` will prevent VideoCompletion events from being tracked. *** ## Video Properties The iOS SDK accepts an untyped `EventProperties` dictionary. Build the nested shape that matches the [canonical schema](/sdks/ctv/video-tracking#video-event-schema) — properties under a top-level `video` parent, in `snake_case`. There is no auto-mapping or auto-nesting like on Android. ### Standard Video Properties ```swift theme={"dark"} let videoProps = try? EventProperties([ "video": [ "title": "Video Title", "genre": ["Action", "Thriller"], "content_type": ["Movie", "Feature"], "age_rating": "PG-13", "runtime": 7200, // Runtime in seconds "country": "US", "original_language": "en", "audio_language": "en", "subtitles": [ "enabled": true, "language": "en" ], "season_number": 1, "episode_number": 5, "consecutive_episodes": 3, "iab_categories": ["IAB1", "IAB2"] ] ]) ``` ### Schema Reference | Property | Type | Description | | ---------------------------- | --------- | --------------------------------------- | | `video.title` | String | Video title | | `video.genre` | \[String] | Video genres (e.g., "Drama", "Comedy") | | `video.content_type` | \[String] | Content types (e.g., "Movie", "Series") | | `video.age_rating` | String | Age rating (e.g., "PG-13", "TV-MA") | | `video.runtime` | Int | Runtime in **seconds** | | `video.country` | String | Origin country | | `video.original_language` | String | Original language code | | `video.audio_language` | String | Audio language code | | `video.subtitles.enabled` | Bool | Whether subtitles are enabled | | `video.subtitles.language` | String | Subtitle language code | | `video.season_number` | Int | Season number (for series) | | `video.episode_number` | Int | Episode number (for series) | | `video.consecutive_episodes` | Int | Consecutive episodes watched | | `video.iab_categories` | \[String] | IAB content taxonomy categories | > 💡 Best Practice > > Track as many properties as possible to enable richer cohort creation and insights. *** ## Page Context (Optional) If the video is displayed within a page context (e.g., embedded in an article), pass a `Context` to associate the tracker with that page: ```swift theme={"dark"} let videoProps = try? EventProperties([ "video": ["title": "Tutorial Video"] ]) let context = Context( title: "How to Use iOS SDK", url: URL(string: "https://example.com/tutorial"), referrer: URL(string: "https://example.com/docs") ) mediaTracker = try? Permutive.shared.createVideoTracker( duration: 120, properties: videoProps, context: context ) ``` ### Context Reference | Property | Type | Description | | ------------ | ------- | ------------------ | | **title** | String? | Page title | | **url** | URL? | Page URL | | **referrer** | URL? | Referring page URL | Providing a `url` in `Context` enables contextual cohort generation for the video content. *** ## Custom Properties The iOS SDK does not take a separate "custom properties" parameter — add custom keys directly to the same `EventProperties` dictionary, alongside the `video` schema fields. Custom keys are emitted at the top level of the event: ```swift theme={"dark"} let props = try? EventProperties([ "video": [ "title": "Episode 5", "season_number": 1, "episode_number": 5 ], "video_id": "vid_12345", "playlist_id": "playlist_abc", "is_premium_content": true, "content_partner": "PartnerXYZ" ]) mediaTracker = try? Permutive.shared.createVideoTracker( duration: 120, properties: props ) ``` *** ## Complete Example ```swift Swift theme={"dark"} import Permutive_iOS import AVKit class VideoPlayerViewController: UIViewController { private var mediaTracker: (NSObject & MediaTrackerProtocol)? private var player: AVPlayer! private var playerObserver: Any? override func viewDidLoad() { super.viewDidLoad() // Set up AVPlayer setupPlayer() } private func setupPlayer() { let url = URL(string: "https://example.com/video.mp4")! player = AVPlayer(url: url) let playerViewController = AVPlayerViewController() playerViewController.player = player addChild(playerViewController) view.addSubview(playerViewController.view) playerViewController.view.frame = view.bounds // Get duration once available, then set up tracker player.currentItem?.asset.loadValuesAsynchronously(forKeys: ["duration"]) { [weak self] in guard let self = self, let duration = self.player.currentItem?.duration, !duration.isIndefinite else { return } let durationSeconds = CMTimeGetSeconds(duration) DispatchQueue.main.async { let props = try? EventProperties([ "video": [ "title": "Introduction to iOS", "genre": ["Educational", "Technology"], "content_type": ["Tutorial"], "age_rating": "G", "runtime": 180, "country": "US", "original_language": "en", "audio_language": "en", "subtitles": ["enabled": false], "iab_categories": ["IAB19"] ], "video_id": "vid_tutorial_001", "is_premium": false ]) let context = Context( title: "iOS Tutorial Page", url: URL(string: "https://example.com/tutorials/ios"), referrer: URL(string: "https://example.com/home") ) self.mediaTracker = try? Permutive.shared.createVideoTracker( duration: durationSeconds, properties: props, context: context ) self.observePlayer() } } } private func observePlayer() { playerObserver = player.observe(\.timeControlStatus) { [weak self] player, _ in switch player.timeControlStatus { case .playing: self?.mediaTracker?.play() case .paused: self?.mediaTracker?.pause() case .waitingToPlayAtSpecifiedRate: break // Buffering @unknown default: break } } } override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) mediaTracker?.stop() // Send VideoCompletion event } deinit { if let observer = playerObserver { player.removeTimeObserver(observer) } } } ``` ```objectivec Objective-C theme={"dark"} @implementation VideoPlayerViewController - (void)viewDidLoad { [super viewDidLoad]; [self setupPlayer]; } - (void)setupPlayer { NSURL *url = [NSURL URLWithString:@"https://example.com/video.mp4"]; self.player = [AVPlayer playerWithURL:url]; AVPlayerViewController *playerVC = [[AVPlayerViewController alloc] init]; playerVC.player = self.player; [self addChildViewController:playerVC]; [self.view addSubview:playerVC.view]; playerVC.view.frame = self.view.bounds; // Get duration once available [self.player.currentItem.asset loadValuesAsynchronouslyForKeys:@[@"duration"] completionHandler:^{ CMTime duration = self.player.currentItem.duration; if (CMTIME_IS_INDEFINITE(duration)) return; NSTimeInterval durationSeconds = CMTimeGetSeconds(duration); dispatch_async(dispatch_get_main_queue(), ^{ NSError *error = nil; PermutiveEventProperties *props = [[PermutiveEventProperties alloc] init:@{ @"video": @{ @"title": @"Introduction to iOS", @"genre": @[@"Educational", @"Technology"], @"content_type": @[@"Tutorial"], @"age_rating": @"G", @"runtime": @180, @"country": @"US", @"original_language": @"en", @"audio_language": @"en", @"subtitles": @{@"enabled": @NO}, @"iab_categories": @[@"IAB19"] }, @"video_id": @"vid_tutorial_001", @"is_premium": @NO } error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"iOS Tutorial Page" url:[NSURL URLWithString:@"https://example.com/tutorials/ios"] referrer:[NSURL URLWithString:@"https://example.com/home"]]; self.mediaTracker = [Permutive.shared createVideoTrackerWithDuration:durationSeconds properties:props context:context error:&error]; [self observePlayer]; }); }]; } - (void)observePlayer { [self.player addObserver:self forKeyPath:@"timeControlStatus" options:NSKeyValueObservingOptionNew context:nil]; } - (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context { if ([keyPath isEqualToString:@"timeControlStatus"]) { if (self.player.timeControlStatus == AVPlayerTimeControlStatusPlaying) { [self.mediaTracker play]; } else if (self.player.timeControlStatus == AVPlayerTimeControlStatusPaused) { [self.mediaTracker pause]; } } } - (void)viewWillDisappear:(BOOL)animated { [super viewWillDisappear:animated]; [self.mediaTracker stop]; // Send VideoCompletion event } - (void)dealloc { [self.player removeObserver:self forKeyPath:@"timeControlStatus"]; } @end ``` *** ## Tracking Custom Events Track custom video-related events using the `track(event:properties:)` method. Both parameters are required (pass `nil` for `properties` if there are none). ```swift theme={"dark"} // User shares video try? mediaTracker?.track( event: "VideoShared", properties: try? EventProperties([ "share_method": "twitter", "video_position_seconds": 45 ]) ) // User adds to favorites try? mediaTracker?.track(event: "VideoAddedToFavorites", properties: nil) // Quality changed try? mediaTracker?.track( event: "VideoQualityChanged", properties: try? EventProperties([ "from_quality": "720p", "to_quality": "1080p" ]) ) ``` *** ## Video Ad Tracking **iOS does not have a native AdTracker.** Emit standard `VideoAdView`, `VideoAdCompletion`, and `VideoAdClicked` events using `Permutive.shared.track(event:properties:)` with properties nested under an `ad` parent per the [canonical schema](/sdks/ctv/video-tracking#ad-event-properties). ```swift theme={"dark"} // When the ad starts try? Permutive.shared.track( event: "VideoAdView", properties: try? EventProperties([ "ad": [ "title": "Product Ad", "duration": 15, "muted": false, "campaign_id": "campaign_123", "creative_id": "creative_456" ] ]) ) // When the ad completes try? Permutive.shared.track( event: "VideoAdCompletion", properties: try? EventProperties([ "ad": [ "title": "Product Ad", "campaign_id": "campaign_123", "creative_id": "creative_456" ] ]) ) ``` See [Video Ad Tracking](/sdks/mobile/ios/features/video-ad-tracking) for the full guide. *** ## Use Cases ```swift theme={"dark"} let props = try? EventProperties([ "video": [ "title": movie.title, "genre": movie.genres, "content_type": ["Movie", "Feature"], "age_rating": movie.rating, "runtime": movie.runtimeSeconds, "country": movie.country, "original_language": movie.language, "iab_categories": movie.iabCategories ] ]) mediaTracker = try? Permutive.shared.createVideoTracker( duration: movieDurationSeconds, properties: props ) ``` ```swift theme={"dark"} let props = try? EventProperties([ "video": [ "title": tutorial.title, "genre": ["Educational"], "content_type": ["Tutorial"], "runtime": tutorial.runtimeSeconds ], "course_id": tutorial.courseId, "module_id": tutorial.moduleId, "difficulty_level": tutorial.difficulty ]) mediaTracker = try? Permutive.shared.createVideoTracker( duration: tutorialDurationSeconds, properties: props ) ``` ```swift theme={"dark"} let props = try? EventProperties([ "video": [ "title": episode.title, "genre": series.genres, "content_type": ["Series", "Episode"], "season_number": episode.season, "episode_number": episode.number, "consecutive_episodes": userWatchData.consecutiveCount, "runtime": episode.runtimeSeconds ] ]) mediaTracker = try? Permutive.shared.createVideoTracker( duration: episodeDurationSeconds, properties: props ) ``` *** ## tvOS Considerations **tvOS Note:** MediaTracker works identically on tvOS. Use the same APIs with your TVUIKit video player or AVPlayerViewController. ```swift theme={"dark"} // tvOS with AVPlayerViewController class TVVideoPlayerViewController: UIViewController { private var mediaTracker: MediaTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() let playerVC = AVPlayerViewController() playerVC.player = AVPlayer(url: videoURL) present(playerVC, animated: true) { self.setupMediaTracker() playerVC.player?.play() } } } ``` *** ## Troubleshooting **Problem:** VideoCompletion events not appearing. **Cause:** `stop()` not called. **Solution:** Always call `stop()` in `viewWillDisappear`: ```swift theme={"dark"} override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) mediaTracker?.stop() // REQUIRED } ``` **Problem:** Engaged time is inaccurate. **Causes:** 1. Not calling `play()` when video plays 2. Not calling `pause()` when video pauses/buffers **Solution:** Track all play/pause events: ```swift theme={"dark"} playerObserver = player.observe(\.timeControlStatus) { [weak self] player, _ in switch player.timeControlStatus { case .playing: try? self?.mediaTracker?.play() case .paused: self?.mediaTracker?.pause() default: break } } ``` **Problem:** `aggregations.VideoEngagement.completion` is missing or nil. **Cause:** Duration not provided when creating the video tracker. **Solution:** Always provide `duration` (in seconds): ```swift theme={"dark"} mediaTracker = try? Permutive.shared.createVideoTracker( duration: videoDurationSeconds // REQUIRED for completion ) ``` **Problem:** Error about multiple trackers. **Cause:** Creating a new PageTracker or video tracker without closing the existing one. **Solution:** Close the existing tracker first: ```swift theme={"dark"} // Close old tracker mediaTracker?.stop() // Now create new tracker mediaTracker = try? Permutive.shared.createVideoTracker(...) ``` See [Common Errors](/sdks/mobile/ios/troubleshooting/common-errors) for more troubleshooting. *** ## Best Practices * Always call `stop()` when video finishes * Provide duration for completion tracking * Track play/pause events accurately * Include as many video properties as possible * Close tracker before creating a new one * Track buffering with pause/play * Forget to call `stop()` * Create multiple MediaTrackers simultaneously * Skip play/pause lifecycle events * Omit video duration *** ## Related Documentation Track video advertisements Track non-video content Custom properties Solve common issues *** ## API Reference ### MediaTrackerProtocol * `play()` — Start/resume video playback * `play(position: TimeInterval)` — Start at a specific position (seconds) * `pause()` — Pause video playback * `stop()` — Complete video tracking (sends `VideoCompletion`) * `set(duration: TimeInterval)` — Update video duration (seconds), if it wasn't known at creation * `track(event: String, properties: EventProperties?) throws` — Track a custom event ### Creating a Video Tracker * `Permutive.shared.createVideoTracker(duration: TimeInterval, properties: EventProperties?, context: Context?) throws -> NSObject & MediaTrackerProtocol` # Initialization Source: https://docs.permutive.com/sdks/mobile/ios/getting-started/initialization Configure and start the Permutive SDK The SDK must be initialized before tracking events or accessing cohort data. Initialization is asynchronous and should happen early in your app lifecycle. ## Basic Initialization ```swift Swift theme={"dark"} import Permutive_iOS func initializePermutive() { guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { print("Failed to create Permutive options") return } Permutive.shared.start(with: options) { error in if let error = error { print("Permutive initialization failed: \(error.localizedDescription)") return } print("Permutive SDK ready") } } ``` ```objectivec Objective-C theme={"dark"} @import Permutive_iOS; - (void)initializePermutive { PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; if (options == nil) { NSLog(@"Failed to create Permutive options"); return; } [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { if (error != nil) { NSLog(@"Permutive initialization failed: %@", error.localizedDescription); return; } NSLog(@"Permutive SDK ready"); }]; } ``` ## Configuration Options The `Options` class accepts several configuration parameters: ### Required Parameters | Parameter | Type | Description | | ---------------- | -------- | ------------------------------ | | `apiKey` | `String` | Your Permutive API key | | `organisationId` | `String` | Your Permutive organisation ID | | `workspaceId` | `String` | Your Permutive workspace ID | ### Optional Configuration ```swift Swift theme={"dark"} guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } // Enable debug logging options.logModes = LogMode.all // Start with options Permutive.shared.start(with: options) { error in // Handle completion } ``` ```objectivec Objective-C theme={"dark"} PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; // Enable debug logging options.logModes = PermutiveLogModeAll; [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { // Handle completion }]; ``` ### Log Modes Control what the SDK logs to the console: | Mode | Description | | --------------- | ------------------------------------------ | | `LogMode.none` | No logging (default for production) | | `LogMode.all` | All messages (recommended for development) | | `LogMode.info` | Informational messages only | | `LogMode.error` | Error messages only | ## Where to Initialize ### UIKit - AppDelegate ```swift Swift theme={"dark"} import UIKit import Permutive_iOS @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { initializePermutive() return true } private func initializePermutive() { guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } Permutive.shared.start(with: options) { error in if let error = error { print("Permutive error: \(error)") } } } } ``` ```objectivec Objective-C theme={"dark"} #import "AppDelegate.h" @import Permutive_iOS; @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self initializePermutive]; return YES; } - (void)initializePermutive { PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { if (error != nil) { NSLog(@"Permutive error: %@", error); } }]; } @end ``` ### SwiftUI - App Struct ```swift theme={"dark"} import SwiftUI import Permutive_iOS @main struct MyApp: App { init() { initializePermutive() } var body: some Scene { WindowGroup { ContentView() } } private func initializePermutive() { guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } Permutive.shared.start(with: options) { error in if let error = error { print("Permutive error: \(error)") } } } } ``` ## Consent Considerations The Permutive SDK assumes consent has been obtained before initialization. If your app requires user consent for tracking, complete your consent flow before calling `start(with:)`. The SDK does not call Apple's App Tracking Transparency (ATT) framework. If you need ATT consent: ```swift theme={"dark"} import AppTrackingTransparency func requestConsentThenInitialize() { if #available(iOS 14, *) { ATTrackingManager.requestTrackingAuthorization { status in switch status { case .authorized: self.initializePermutive() case .denied, .restricted: // Handle accordingly - you may still initialize // Permutive without IDFA tracking self.initializePermutive() case .notDetermined: break @unknown default: break } } } else { initializePermutive() } } ``` **IDFA is not required.** Permutive works effectively without IDFA. Consider using `identifierForVendor` or hashed email addresses instead. See [IDFA Provider](/sdks/mobile/ios/integrations/idfa-provider) for details. ## Initialization with Context You can provide initial context during initialization: ```swift Swift theme={"dark"} let context = Context( title: "App Launch", url: URL(string: "https://example.com/app"), referrer: nil ) Permutive.shared.start(with: options, context: context) { error in // Handle completion } ``` ```objectivec Objective-C theme={"dark"} PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"App Launch" url:[NSURL URLWithString:@"https://example.com/app"] referrer:nil]; [[Permutive shared] startWith:options context:context completion:^(NSError *error) { // Handle completion }]; ``` ## Checking Initialization Status The SDK provides properties to check its current state: ```swift theme={"dark"} // Get the current user ID (available after initialization) let userId = Permutive.shared.currentUserId // Check current cohorts let cohorts = Permutive.shared.cohorts ``` ## Error Handling Handle initialization errors appropriately: ```swift Swift theme={"dark"} Permutive.shared.start(with: options) { error in if let error = error { // Log the error for debugging print("Permutive initialization failed: \(error.localizedDescription)") // Optionally report to your error tracking service // ErrorTracker.report(error) // The app can continue without Permutive // SDK calls will be no-ops or return empty data return } // SDK is ready - proceed with tracking print("Permutive ready, user ID: \(Permutive.shared.currentUserId)") } ``` ```objectivec Objective-C theme={"dark"} [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { if (error != nil) { NSLog(@"Permutive initialization failed: %@", error.localizedDescription); return; } NSLog(@"Permutive ready, user ID: %@", [[Permutive shared] currentUserId]); }]; ``` ## tvOS Considerations **tvOS Note:** The initialization process is identical on tvOS. The SDK automatically handles platform differences. App Tracking Transparency and IDFA are available on tvOS from version 14.5 onwards. ## Best Practices * Initialize as early as possible in the app lifecycle * Handle initialization errors gracefully * Complete consent flows before initialization * Enable debug logging during development * Store credentials securely (consider using a configuration file or build settings) * Don't initialize multiple times * Don't block the main thread waiting for initialization * Don't hard-code credentials in source control * Don't assume immediate availability of cohort data after initialization ## Troubleshooting **Problem:** No error, but SDK doesn't seem to work. **Solutions:** * Enable debug logging: `options.logModes = LogMode.all` * Check credentials are correct * Verify network connectivity **Problem:** Initialization fails with credential error. **Solutions:** * Verify API key, organization ID, and workspace ID from your dashboard * Check for extra whitespace or newlines in credential strings * Ensure credentials match the correct environment (staging vs production) **Problem:** Events tracked before initialization completes are lost. **Solution:** Wait for the completion callback before tracking: ```swift theme={"dark"} Permutive.shared.start(with: options) { error in guard error == nil else { return } // Now safe to track self.startTracking() } ``` ## Next Steps Verify your integration is working Track page views and engagement # Installation Source: https://docs.permutive.com/sdks/mobile/ios/getting-started/installation Add the Permutive SDK to your iOS or tvOS project The Permutive iOS SDK can be installed via Swift Package Manager or CocoaPods. ## Requirements | Requirement | Version | | ----------- | --------------------------- | | iOS | 12.0+ | | tvOS | 12.0+ | | Xcode | 13.0+ | | Swift | 5.0+ | | CocoaPods | 1.9.1+ (if using CocoaPods) | ## Swift Package Manager Swift Package Manager is the recommended installation method for new projects. In Xcode, go to **File → Add Package Dependencies** In the search field, enter: ``` https://github.com/permutive-engineering/permutive-ios-spm ``` Choose a dependency rule: * **Up to Next Major Version**: `2.2.0` (recommended) * **Exact Version**: `2.2.0` Select **Permutive\_iOS** and add it to your target ### Package.swift (for packages) If you're adding Permutive to a Swift package, add it to your `Package.swift`: ```swift theme={"dark"} dependencies: [ .package(url: "https://github.com/permutive-engineering/permutive-ios-spm", from: "2.2.0") ], targets: [ .target( name: "YourTarget", dependencies: [ .product(name: "Permutive_iOS", package: "permutive-ios-spm") ] ) ] ``` ## CocoaPods ### Basic Installation Add the Permutive pod to your `Podfile`: ```ruby theme={"dark"} target 'YourApp' do platform :ios, '12.0' pod 'Permutive_iOS', '~> 2.2.0' end ``` Then install: ```bash theme={"dark"} pod install ``` ### tvOS Installation For tvOS targets, specify the tvOS platform: ```ruby theme={"dark"} target 'YourTVApp' do platform :tvos, '12.0' pod 'Permutive_iOS', '~> 2.2.0' end ``` ### Multi-Platform Podfile For apps supporting both iOS and tvOS: ```ruby theme={"dark"} # Shared dependencies def shared_pods pod 'Permutive_iOS', '~> 2.2.0' end target 'YourApp-iOS' do platform :ios, '12.0' shared_pods end target 'YourApp-tvOS' do platform :tvos, '12.0' shared_pods end ``` ### Updating the SDK To update to the latest version: ```bash theme={"dark"} pod update Permutive_iOS ``` ## Importing the SDK After installation, import Permutive in your Swift or Objective-C files: ```swift Swift theme={"dark"} import Permutive_iOS ``` ```objectivec Objective-C theme={"dark"} @import Permutive_iOS; ``` ## Verifying Installation After installing, verify the SDK is accessible: ```swift Swift theme={"dark"} import Permutive_iOS // This should compile without errors let _ = Permutive.shared ``` ```objectivec Objective-C theme={"dark"} @import Permutive_iOS; // This should compile without errors [Permutive shared]; ``` Build your project (⌘B) to confirm there are no import errors. ## Mac Catalyst Support The SDK supports Mac Catalyst. When using Swift Package Manager, add the package as normal - it works for both iOS and Mac Catalyst targets. For CocoaPods, the standard iOS pod works with Catalyst projects. ## Troubleshooting **Problem:** `Unable to find a specification for 'Permutive_iOS'` **Solutions:** * Update your CocoaPods repo: `pod repo update` * Ensure CocoaPods is version 1.9.1 or later: `pod --version` * Try clearing the cache: `pod cache clean --all` **Problem:** Xcode cannot resolve the package. **Solutions:** * Check your network connection * Reset package caches: **File → Packages → Reset Package Caches** * Verify the URL is correct: `https://github.com/permutive-engineering/permutive-ios-spm` **Problem:** `No such module 'Permutive_iOS'` **Solutions:** * Clean build folder: **Product → Clean Build Folder** (⇧⌘K) * For CocoaPods: Ensure you opened the `.xcworkspace` file, not `.xcodeproj` * Restart Xcode **Problem:** Bitcode-related build errors. **Solution:** Bitcode is no longer required for App Store submission. Disable it in your target's Build Settings: set **Enable Bitcode** to **No**. ## Next Steps Configure and start the SDK Complete setup walkthrough # Quick Start Source: https://docs.permutive.com/sdks/mobile/ios/getting-started/quick-start Get up and running with the Permutive iOS SDK in minutes This guide walks you through installing the SDK, initializing it, and tracking your first page view. ## Prerequisites * Xcode 13.0 or later * iOS 12.0+ or tvOS 12.0+ deployment target * Your Permutive **API Key**, **Organization ID**, and **Workspace ID** (from your dashboard) ## Step 1: Install the SDK 1. In Xcode, go to **File → Add Package Dependencies** 2. Enter the package URL: ``` https://github.com/permutive-engineering/permutive-ios-spm ``` 3. Select **Permutive\_iOS** as the package product 4. Click **Add Package** Add to your `Podfile`: ```ruby theme={"dark"} target 'YourApp' do platform :ios, '12.0' pod 'Permutive_iOS', '~> 2.2.0' end ``` Then run: ```bash theme={"dark"} pod install ``` ## Step 2: Initialize the SDK Initialize Permutive early in your app lifecycle, typically in your `AppDelegate` or `SceneDelegate`. ```swift Swift theme={"dark"} import UIKit import Permutive_iOS @main class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { initializePermutive() return true } private func initializePermutive() { guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { print("Failed to create Permutive options") return } Permutive.shared.start(with: options) { error in if let error = error { print("Permutive initialization failed: \(error.localizedDescription)") return } print("Permutive SDK ready") } } } ``` ```objectivec Objective-C theme={"dark"} #import "AppDelegate.h" @import Permutive_iOS; @implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self initializePermutive]; return YES; } - (void)initializePermutive { PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; if (options == nil) { NSLog(@"Failed to create Permutive options"); return; } [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { if (error != nil) { NSLog(@"Permutive initialization failed: %@", error.localizedDescription); return; } NSLog(@"Permutive SDK ready"); }]; } @end ``` ## Step 3: Track Your First Page View Use `PageTracker` to track page views. This is the recommended approach for most tracking scenarios. ```swift Swift theme={"dark"} import UIKit import Permutive_iOS class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() // Create event properties let properties = try? EventProperties([ "category": "news", "author": "Jane Smith" ]) // Create page context let context = Context( title: "Breaking News: Tech Advances", url: URL(string: "https://example.com/articles/tech-advances"), referrer: nil ) // Create the page tracker pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() // Starts tracking, fires Pageview event } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) pageTracker?.pause() // Pauses engagement timer } deinit { pageTracker?.stop() // Stops tracking, fires PageViewComplete event } } ``` ```objectivec Objective-C theme={"dark"} #import "ArticleViewController.h" @import Permutive_iOS; @interface ArticleViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; // Create event properties NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"category": @"news", @"author": @"Jane Smith"} error:&error]; // Create page context PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Breaking News: Tech Advances" url:[NSURL URLWithString:@"https://example.com/articles/tech-advances"] referrer:nil]; // Create the page tracker self.pageTracker = [[Permutive shared] createPageTrackerWithProperties:properties context:context error:&error]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; // Starts tracking } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.pageTracker pause]; // Pauses engagement timer } - (void)dealloc { [self.pageTracker stop]; // Stops tracking } @end ``` ## Step 4: Verify the Integration Enable debug logging to confirm events are being sent: ```swift Swift theme={"dark"} guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } // Enable all logging options.logModes = LogMode.all Permutive.shared.start(with: options) { error in // ... } ``` ```objectivec Objective-C theme={"dark"} PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; options.logModes = PermutiveLogModeAll; [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { // ... }]; ``` Run your app and check the Xcode console for: ``` Permutive: [info] SDK ready Permutive: [info] Accepted: 1 / 1 ``` The "Accepted: 1 / 1" message confirms your event was successfully sent to Permutive servers. ## Next Steps CocoaPods and SPM configuration options Advanced SDK configuration Complete PageTracker guide Track users across sessions # Verification Source: https://docs.permutive.com/sdks/mobile/ios/getting-started/verification Verify your Permutive iOS SDK integration is working correctly After installing and initializing the SDK, verify that events are being sent correctly before releasing to production. ## Enable Debug Logging Enable debug logging to see SDK activity in the Xcode console: ```swift Swift theme={"dark"} guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } // Enable all log messages options.logModes = LogMode.all Permutive.shared.start(with: options) { error in // ... } ``` ```objectivec Objective-C theme={"dark"} PermutiveOptions *options = [[PermutiveOptions alloc] initWithApiKey:@"" organisationId:@"" workspaceId:@""]; // Enable all log messages options.logModes = PermutiveLogModeAll; [[Permutive shared] startWith:options context:nil completion:^(NSError *error) { // ... }]; ``` ## What to Look For ### Successful Initialization When the SDK initializes successfully, you'll see: ``` Permutive: [info] SDK ready ``` ### Successful Event Tracking When events are accepted by Permutive servers: ``` Permutive: [info] Accepted: 1 / 1 ``` The format is `Accepted: X / Y` where X is the number of events accepted and Y is the total sent. ### Schema Validation Errors If event properties don't match your schema: ``` Permutive: [error] Encountered 1 event rejection! Permutive: [error] Error 1: A validation check carried out by the server did not succeed.(1007) Permutive: [error] Error 1: Schema validation failed with reason(s): [#: 1 schema violations found;#: extraneous key [invalid_key] is not permitted] ``` Schema validation errors mean events are being rejected. Fix the property names or types to match your event schema in the Permutive dashboard. ## Verification Checklist Look for `SDK ready` in the console after app launch. Navigate through your app and look for `Accepted: X / X` messages. Ensure there are no `event rejection` error messages. Log into your Permutive dashboard and verify events appear (may take up to 5 minutes). ## Verification Code Example Add this verification helper during development: ```swift Swift theme={"dark"} import Permutive_iOS class PermutiveVerification { static func verify() { // Check user ID let userId = Permutive.shared.currentUserId print("✅ Permutive User ID: \(userId)") // Check cohorts let cohorts = Permutive.shared.cohorts print("✅ Current cohorts: \(cohorts)") // Check activations let activations = Permutive.shared.activations print("✅ Activations: \(activations)") // Track a test event do { let properties = try EventProperties([ "verification_test": true, "timestamp": Date().timeIntervalSince1970 ]) try Permutive.shared.track(event: "VerificationTest", properties: properties) print("✅ Test event sent") } catch { print("❌ Failed to send test event: \(error)") } } } // Call after initialization completes Permutive.shared.start(with: options) { error in guard error == nil else { return } PermutiveVerification.verify() } ``` ```objectivec Objective-C theme={"dark"} @import Permutive_iOS; @interface PermutiveVerification : NSObject + (void)verify; @end @implementation PermutiveVerification + (void)verify { // Check user ID NSString *userId = [[Permutive shared] currentUserId]; NSLog(@"✅ Permutive User ID: %@", userId); // Check cohorts NSSet *cohorts = [[Permutive shared] cohorts]; NSLog(@"✅ Current cohorts: %@", cohorts); // Check activations NSDictionary *activations = [[Permutive shared] activations]; NSLog(@"✅ Activations: %@", activations); // Track a test event NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"verification_test": @YES} error:&error]; [[Permutive shared] trackWithEvent:@"VerificationTest" properties:properties error:&error]; if (error == nil) { NSLog(@"✅ Test event sent"); } else { NSLog(@"❌ Failed to send test event: %@", error); } } @end ``` ## PageTracker Verification Verify PageTracker is working correctly: ```swift Swift theme={"dark"} class TestViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() let properties = try? EventProperties(["test_page": true]) let context = Context( title: "Verification Test Page", url: URL(string: "https://example.com/test"), referrer: nil ) pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) print("✅ PageTracker created") } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) do { try pageTracker?.resume() print("✅ PageTracker resumed - Pageview event should be sent") } catch { print("❌ PageTracker resume failed: \(error)") } } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) pageTracker?.pause() print("✅ PageTracker paused") } deinit { pageTracker?.stop() print("✅ PageTracker stopped - PageViewComplete event should be sent") } } ``` ```objectivec Objective-C theme={"dark"} @interface TestViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation TestViewController - (void)viewDidLoad { [super viewDidLoad]; NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"test_page": @YES} error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Verification Test Page" url:[NSURL URLWithString:@"https://example.com/test"] referrer:nil]; self.pageTracker = [[Permutive shared] createPageTrackerWithProperties:properties context:context error:&error]; NSLog(@"✅ PageTracker created"); } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; NSError *error = nil; [self.pageTracker resumeAndReturnError:&error]; if (error == nil) { NSLog(@"✅ PageTracker resumed"); } else { NSLog(@"❌ PageTracker resume failed: %@", error); } } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.pageTracker pause]; NSLog(@"✅ PageTracker paused"); } - (void)dealloc { [self.pageTracker stop]; NSLog(@"✅ PageTracker stopped"); } @end ``` ## Common Verification Issues **Problem:** Console is silent, no Permutive logs appear. **Solutions:** * Confirm `logModes = LogMode.all` is set before calling `start()` * Check Xcode console filter isn't hiding messages * Verify SDK is actually being initialized (add a breakpoint) **Problem:** Events sent but rejected by server. **Solutions:** * Check event name matches schema (alphanumeric and underscores only) * Verify property names and types match your Permutive dashboard schema * Remove any extra properties not in the schema **Problem:** Console shows `Accepted` but events not in dashboard. **Solutions:** * Wait up to 5 minutes for events to process * Verify you're looking at the correct workspace * Check the date range filter in the dashboard * Confirm credentials match the dashboard environment **Problem:** `cohorts` returns an empty set. **Solutions:** * Cohorts are evaluated server-side and may take time to populate * Ensure you've tracked sufficient events to qualify for cohorts * Check with your Customer Success Manager that cohorts are configured ## Disable Logging for Production Always disable debug logging before releasing to production to avoid performance overhead and prevent sensitive data from appearing in device logs. ```swift Swift theme={"dark"} #if DEBUG options.logModes = LogMode.all #else options.logModes = LogMode.none #endif ``` ```objectivec Objective-C theme={"dark"} #ifdef DEBUG options.logModes = PermutiveLogModeAll; #else options.logModes = PermutiveLogModeNone; #endif ``` ## Next Steps Once verification passes: Implement page tracking throughout your app Set up user identity tracking Integrate with GAM for ad targeting Troubleshoot common problems # Migration Guide: v2.6.x Source: https://docs.permutive.com/sdks/mobile/ios/guides/migration/v2-6 Upgrade to Permutive iOS SDK v2.6.x and opt into config-driven automatic ID collection This guide covers upgrading to Permutive iOS SDK v2.6.x, which introduces **config-driven automatic ID collection**. When enabled for your workspace, the SDK automatically collects the user's IDFA, IDFV, and IP address as identity aliases — with no provider code required. **Migration Difficulty:** Easy | **Estimated Time:** 15 minutes | **Breaking Changes:** None ## What's New in v2.6.0 The SDK captures the IDFA as an `idfa` alias when enabled in your workspace config and the user has authorized tracking The SDK captures the `identifierForVendor` as an `idfv` alias — no user permission required The SDK captures the user's IP as an `ip_address` alias from an internal endpoint — no app changes required **Good news:** This release is fully backward compatible with no breaking changes or deprecations. Automatic collection is **off by default** and is enabled remotely through your dashboard. ## How Automatic ID Collection Works Collection is driven by your workspace configuration, not by app code. Once you enable it for your workspace in the dashboard, the SDK picks it up on its next config refresh. * Stored as an alias with tag **`idfa`**, the priority defined in your config. * **Only collected when the user has authorized tracking** via App Tracking Transparency (ATT status `authorized`). Requires iOS 14+. * If ATT status is **not determined**, collection is skipped until the user responds — the SDK does **not** present the ATT prompt itself. * If ATT status is **denied** or **restricted**, no alias is stored and any existing `idfa` alias is cleared. * A zeroed-out IDFA (`00000000-0000-0000-0000-000000000000`) is treated as no IDFA — nothing is stored. * If an alias with the same tag and value already exists, storage is skipped to avoid duplicates. * Stored as an alias with tag **`idfv`**, the priority defined in your config. * Uses `identifierForVendor` — **no user permission is required**, and it works on both iOS and tvOS. * Stored as an alias with tag **`ip_address`**, the priority defined in your config. * Retrieved from an internal endpoint and updated when the IP changes. * **No app or privacy-manifest changes are required** for IP collection. ## Standard Upgrade Upgrading the SDK requires only a dependency bump. Update the package to `2.6.0` (or later) in Xcode via **File → Packages → Update to Latest Package Versions**, or pin the version in `Package.swift`: ```swift theme={"dark"} .package(url: "https://github.com/permutive/permutive-ios", from: "2.6.0") ``` Update your `Podfile`: ```ruby theme={"dark"} pod 'Permutive_iOS', '~> 2.6.0' ``` Then run: ```bash theme={"dark"} pod update Permutive_iOS ``` Automatic collection stays **off** until you enable it for your workspace in the dashboard, so no further changes are needed to complete the upgrade. ## Opting Into IDFA Collection The steps below are **only required if you opt into automatic IDFA collection**. They do not apply to a standard version upgrade, and they are not needed for automatic IDFV or IP address collection (which require no app changes). The Permutive SDK links the `AppTrackingTransparency` framework so it can read the ATT status. This affects your App Store submission and privacy declarations even if your app never used ATT before — follow the path that matches your app. ### If you already use App Tracking Transparency Your app already declares `NSUserTrackingUsageDescription` and requests authorization, so the only requirement is to keep your **privacy manifest** consistent. Xcode **merges** the SDK's `PrivacyInfo.xcprivacy` with your app's at build time. Ensure your `NSPrivacyCollectedDataTypes` entries match what data your app actually collects. ### If you opt into IDFA collection but do not already use App Tracking Transparency To collect the IDFA, the SDK reads the ATT authorization status and the advertising identifier. If your app does not already use ATT, you need to add a tracking usage description and decide how your app declares tracking before enabling IDFA collection. The presence of `AppTrackingTransparency` symbols in the binary requires a `NSUserTrackingUsageDescription` key in `Info.plist` to pass App Store review: ```xml theme={"dark"} NSUserTrackingUsageDescription We use this identifier to deliver and measure personalized advertising. ``` The value can be any descriptive string — **it will not be shown to users** unless your app explicitly calls `ATTrackingManager.requestTrackingAuthorization()`. Without this key, the app submission will be rejected regardless of whether IDFA collection is active. The Permutive SDK does **not** present the ATT prompt for you. If you want IDFA to actually be collected, your app must request authorization (and be granted it) — otherwise only IDFV/IP are collected. In App Store Connect, under **App Privacy → Data Types**, declare: * **`Identifiers` → `Device ID`** — collected, linked to the user's identity, used for tracking * **Purposes:** whichever apply to your use of Permutive (typically Third-Party Advertising, Analytics) Keep your privacy declarations in sync with what the SDK actually collects. Misdeclaring collected identifiers can lead to App Store rejections. ## Verifying Collection Enable developer logging and look for the identity being set: ```swift theme={"dark"} Permutive.shared.setDeveloperMode(enabled: true) ``` Look for log lines such as: ``` IDFA auto-collection success ``` If IDFA is skipped, the log states why (for example, `ATT not yet determined by user`, `ATT status is denied`, or `IDFA is zeroed out`). See the [Verification Guide](/sdks/mobile/ios/getting-started/verification) for complete steps. ## Manual vs. Automatic IDFA Collection If you currently set the IDFA yourself (for example via `setIdentityForIDFA` — see the [IDFA Provider](/sdks/mobile/ios/integrations/idfa-provider) guide), we recommend **removing the manual code** once automatic collection is enabled, unless you have a specific use case for it. Automatic, config-driven collection covers the same capture, lets you enable or disable it without shipping an app update, and is managed centrally from the dashboard. Running both is safe in the meantime — automatic collection skips storage when an `idfa` alias with the same value already exists, so you won't get duplicate identities during the transition. | | Manual (`setIdentityForIDFA`) | Automatic (config-driven) | | ----------------------------------------- | ----------------------------- | ------------------------- | | Enablement | App code | Workspace config (remote) | | App update needed to toggle | Yes | No | | ATT authorization required | Yes (iOS 14+) | Yes (iOS 14+) | | `NSUserTrackingUsageDescription` required | Yes | Yes | | Available on tvOS | Yes (tvOS 14.5+) | Yes (tvOS 14.5+) | | Alias tag | `idfa` | `idfa` | ## Rollback If you need to roll back to v2.5.x, pin the previous version: ```swift theme={"dark"} .package(url: "https://github.com/permutive/permutive-ios", from: "2.5.2") ``` ```ruby theme={"dark"} pod 'Permutive_iOS', '~> 2.5.2' ``` You can leave the `NSUserTrackingUsageDescription` key in your `Info.plist` — it is harmless when collection is disabled. ## Getting Help Manual IDFA capture, ATT, and privacy considerations How aliases and identities work Verify identity capture Solutions to common issues # IDFA Provider Source: https://docs.permutive.com/sdks/mobile/ios/integrations/idfa-provider Apple advertising identifier integration and privacy considerations This guide covers using the Identifier for Advertisers (IDFA) with the Permutive SDK, including App Tracking Transparency requirements and privacy best practices. ## Should you collect IDFA? IDFA is opt-in only, it's gated behind Apple's App Tracking Transparency (ATT) prompt, so it's never available for 100% of your users. When a user consents, the IDFA can be collected as an additional, stable identifier for that user. **Config-driven auto-collection is available from v2.6.0.** If your workspace has it enabled, the SDK can automatically collect the IDFA (and IDFV / IP) as aliases, no manual `setIdentityForIDFA` code required. The manual approach below is still supported. See the [v2.6 Migration Guide](/sdks/mobile/ios/guides/migration/v2-6) for setup and the privacy/App Store implications. ## Why opting in can be worth it 1. **Consent rates are rising, not collapsing.** The industry-wide ATT opt-in rate reached roughly **35% by Q2 2025**, up from \~34% in 2023 and \~34.5% in 2024, a steady upward trend as prompt design and onboarding flows have matured. 2. **A stable, consented identifier.** For users who consent, the IDFA stays consistent for that user, giving a reliable signal to resolve their identity accurately. 3. **A standard iOS identifier.** IDFA uses Apple's own identifier format, so it fits into your existing identity setup without custom handling. 4. **Complements your other identifiers.** IDFA adds to the identity you already collect (hashed email, IDFV) rather than replacing it, helping build a more complete picture of the consenting share of your audience. ## What to weigh before opting in 1. **Coverage is partial.** Even at healthy opt-in rates, a meaningful share of users will decline, so IDFA should never be your only identifier. Pair it with hashed email and IDFV (see [Recommended Alternatives](#recommended-alternatives)). 2. **Extra implementation.** Requires integrating the ATT framework and requesting permission at the right moment. 3. **App Store compliance.** You must justify IDFA usage and declare it accurately in App Store Connect. ## Recommended Alternatives ### 1. Identifier for Vendor (IDFV) A consistent identifier across your apps from the same vendor: ```swift theme={"dark"} import UIKit import Permutive_iOS func setVendorIdentity() { guard let idfv = UIDevice.current.identifierForVendor?.uuidString else { return } let alias = Alias(tag: "idfv", identity: idfv, priority: 2) try? Permutive.shared.setIdentities(aliases: [alias]) } ``` **Benefits:** * No user permission required * Consistent across app installs (until uninstall) * Available on both iOS and tvOS * No App Store justification needed ### 2. Hashed Email Address The most reliable cross-device identifier: ```swift theme={"dark"} import CryptoKit import Permutive_iOS func setEmailIdentity(email: String) { let normalized = email.trimmingCharacters(in: .whitespaces).lowercased() let data = Data(normalized.utf8) let hash = SHA256.hash(data: data) let emailHash = hash.compactMap { String(format: "%02x", $0) }.joined() let alias = Alias(tag: "email_sha256", identity: emailHash, priority: 0) try? Permutive.shared.setIdentities(aliases: [alias]) } ``` **Benefits:** * Works across devices and platforms * Highest priority for identity resolution * No Apple framework dependencies * User provided and expected ### 3. Internal User ID Your system's user identifier: ```swift theme={"dark"} func setUserIdentity(userId: String) { let alias = Alias(tag: "internal_id", identity: userId, priority: 1) try? Permutive.shared.setIdentities(aliases: [alias]) } ``` ## App Tracking Transparency If you still need IDFA, follow these steps: ### 1. Add Usage Description Add to your `Info.plist`: ```xml theme={"dark"} NSUserTrackingUsageDescription We use this identifier to personalize your ad experience. ``` ### 2. Request Permission ```swift Swift theme={"dark"} import AppTrackingTransparency import AdSupport import Permutive_iOS class TrackingPermissionManager { func requestTrackingPermission() { // Only available on iOS 14+ if #available(iOS 14, *) { ATTrackingManager.requestTrackingAuthorization { status in switch status { case .authorized: self.setIDFAIdentity() case .denied: print("User denied tracking") case .restricted: print("Tracking restricted") case .notDetermined: print("Not determined") @unknown default: break } } } else { // iOS 13 and earlier - no ATT required setIDFAIdentity() } } private func setIDFAIdentity() { let idfa = ASIdentifierManager.shared().advertisingIdentifier // Check if IDFA is valid (not all zeros) guard idfa != UUID(uuidString: "00000000-0000-0000-0000-000000000000") else { print("IDFA not available (tracking denied or restricted)") return } do { try Permutive.shared.setIdentityForIDFA(idfa) print("IDFA set successfully") } catch { print("Failed to set IDFA: \(error)") } } } ``` ```objectivec Objective-C theme={"dark"} #import #import @import Permutive_iOS; @implementation TrackingPermissionManager - (void)requestTrackingPermission { if (@available(iOS 14, *)) { [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) { if (status == ATTrackingManagerAuthorizationStatusAuthorized) { [self setIDFAIdentity]; } else { NSLog(@"Tracking not authorized: %ld", (long)status); } }]; } else { // iOS 13 and earlier [self setIDFAIdentity]; } } - (void)setIDFAIdentity { NSUUID *idfa = [[ASIdentifierManager sharedManager] advertisingIdentifier]; // Check if IDFA is valid NSUUID *zeroUUID = [[NSUUID alloc] initWithUUIDString:@"00000000-0000-0000-0000-000000000000"]; if ([idfa isEqual:zeroUUID]) { NSLog(@"IDFA not available"); return; } NSError *error = nil; [Permutive.shared setIdentityForIDFA:idfa error:&error]; if (error) { NSLog(@"Failed to set IDFA: %@", error); } else { NSLog(@"IDFA set successfully"); } } @end ``` ### 3. Check Status Before Requesting ```swift theme={"dark"} func checkAndRequestTracking() { if #available(iOS 14, *) { let status = ATTrackingManager.trackingAuthorizationStatus switch status { case .notDetermined: // Can request permission requestTrackingPermission() case .authorized: // Already authorized setIDFAIdentity() case .denied, .restricted: // Cannot use IDFA useAlternativeIdentity() @unknown default: break } } } ``` ### 4. When to Request Don't request tracking permission immediately on app launch. Wait for an appropriate moment when the user understands the value. ```swift theme={"dark"} // Good: Request after user has engaged with the app func onFirstContentView() { // User has started using the app requestTrackingPermission() } // Good: Request when user is about to see ads func onPrepareToPresentAds() { requestTrackingPermission() } // Bad: Requesting immediately on launch func applicationDidFinishLaunching() { // Don't do this - user hasn't understood the app yet // requestTrackingPermission() } ``` ## Using setIdentityForIDFA The SDK provides a dedicated method for IDFA: ```swift theme={"dark"} do { try Permutive.shared.setIdentityForIDFA(idfa) } catch { // IDFA was invalid (all zeros) or otherwise unusable print("setIdentityForIDFA failed: \(error)") } ``` This method: * Sets an alias with the reserved tag `"idfa"` * Validates the IDFA is not all zeros * Throws an error if IDFA is invalid ## Apple Privacy Information When submitting to the App Store, you must declare data collection. For apps using Permutive: ### Without IDFA If you're NOT using IDFA, Permutive's SDK data collection is: * **Identifiers:** Device ID (vendor identifier if used) * **Usage Data:** Product interaction * **Purpose:** Analytics, advertising ### With IDFA If you ARE using IDFA, also declare: * **Identifiers:** Device ID (IDFA) * **Purpose:** Third-party advertising, tracking For complete privacy information, see Apple's [App Store data collection policies](https://developer.apple.com/app-store/app-privacy-details/). ## tvOS Considerations **tvOS Note:** App Tracking Transparency and IDFA are available on tvOS from version 14.5 onwards. ```swift theme={"dark"} #if os(tvOS) // tvOS - use vendor identifier if let idfv = UIDevice.current.identifierForVendor?.uuidString { let alias = Alias(tag: "idfv", identity: idfv, priority: 2) try? Permutive.shared.setIdentities(aliases: [alias]) } #else // iOS - can request IDFA if needed requestTrackingPermission() #endif ``` ## Best Practices * Use `identifierForVendor` as a reliable alternative * Use hashed email for cross-device identity * Request ATT permission at an appropriate time * Explain the value to users before requesting * Handle all authorization statuses gracefully * Have fallback identifiers when IDFA unavailable * Don't rely solely on IDFA for identity * Don't request permission immediately on launch * Don't assume IDFA is available * Don't forget to update App Store privacy declarations ## Troubleshooting **Problem:** IDFA call fails with error. **Cause:** IDFA is all zeros (tracking denied/restricted). **Solution:** Check authorization status first and use alternative identifiers: ```swift theme={"dark"} if ATTrackingManager.trackingAuthorizationStatus == .authorized { try Permutive.shared.setIdentityForIDFA(idfa) } else { setAlternativeIdentity() } ``` **Problem:** `requestTrackingAuthorization` doesn't show prompt. **Possible Causes:** * Missing `NSUserTrackingUsageDescription` in Info.plist * User already responded (check status first) * Running on iOS 13 or earlier * Running on simulator (may behave differently) **Problem:** App Store rejects app for tracking without permission. **Solution:** Ensure you: * Request ATT permission before accessing IDFA * Have clear `NSUserTrackingUsageDescription` * Accurately declare data usage in App Store Connect ## Related Documentation All identity options SDK setup and consent Ad targeting Common problems # Integrations Source: https://docs.permutive.com/sdks/mobile/ios/integrations/overview Connect the iOS SDK with ad platforms and tracking providers The Permutive iOS SDK integrates with major ad platforms to enable audience targeting. For detailed setup instructions, see the main integration documentation for each platform. ## Ad Server Integrations Set up GAM targeting for iOS apps Configure Xandr ad platform targeting ## SDK Providers Apple advertising identifier tracking and App Tracking Transparency # iOS SDK Source: https://docs.permutive.com/sdks/mobile/ios/overview Integrate Permutive into your iOS and tvOS applications for user segmentation, personalization, and ad targeting ## Overview The Permutive iOS SDK enables user segmentation, personalization, and ad targeting in your iOS and tvOS applications. Track user behavior, manage identities across devices, and deliver targeted advertising through integrations with major ad platforms. **Current Version:** 2.2.0 **Platform Support:** The SDK supports iOS 12.0+ and tvOS 12.0+. Both platforms share the same API with minor differences noted in the documentation. ## Getting Started New to the Permutive iOS SDK? Start here. Get up and running with your first page view in minutes CocoaPods and Swift Package Manager setup SDK initialization patterns and configuration Verify your integration is working correctly ## Core Concepts Understand the fundamental concepts of the Permutive SDK. Track users across devices and sessions Structure and validate event data Understanding user segmentation Content-based real-time targeting ## Features Detailed guides for specific SDK features. Track pageviews and user engagement (recommended approach) Track custom events Track video content viewing Track video advertisement engagement React to cohort changes in real-time ## Integrations Connect Permutive with ad platforms and other services. Google Ad Manager, Xandr, and more Apple advertising identifier tracking ## Common Tasks **PageTracker is the recommended approach** for tracking user interactions as it integrates with Permutive's standard events and provides richer insights. ```swift Swift theme={"dark"} import UIKit import Permutive_iOS class ArticleViewController: UIViewController { private var pageTracker: PageTrackerProtocol? override func viewDidLoad() { super.viewDidLoad() let properties = try? EventProperties([ "category": "sports", "author": "John Doe" ]) let context = Context( title: "Article Title", url: URL(string: "https://example.com/article"), referrer: nil ) pageTracker = try? Permutive.shared.createPageTracker( properties: properties, context: context ) } override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() } override func viewDidDisappear(_ animated: Bool) { super.viewDidDisappear(animated) pageTracker?.pause() } deinit { pageTracker?.stop() } } ``` ```objectivec Objective-C theme={"dark"} #import "ArticleViewController.h" @import Permutive_iOS; @interface ArticleViewController () @property (nonatomic, strong) NSObject *pageTracker; @end @implementation ArticleViewController - (void)viewDidLoad { [super viewDidLoad]; NSError *error = nil; PermutiveEventProperties *properties = [[PermutiveEventProperties alloc] init:@{@"category": @"sports", @"author": @"John Doe"} error:&error]; PermutiveContext *context = [[PermutiveContext alloc] initWithTitle:@"Article Title" url:[NSURL URLWithString:@"https://example.com/article"] referrer:nil]; self.pageTracker = [Permutive.shared createPageTrackerWithProperties:properties context:context error:&error]; } - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [self.pageTracker resumeAndReturnError:nil]; } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [self.pageTracker pause]; } - (void)dealloc { [self.pageTracker stop]; } @end ``` ```swift Swift theme={"dark"} let aliases = [ Alias(tag: "email_sha256", identity: emailHash), Alias(tag: "internal_id", identity: userId, priority: 1) ] try? Permutive.shared.setIdentities(aliases: aliases) ``` ```objectivec Objective-C theme={"dark"} PermutiveAlias *emailAlias = [[PermutiveAlias alloc] initWithTag:@"email_sha256" identity:emailHash]; PermutiveAlias *idAlias = [[PermutiveAlias alloc] initWithTag:@"internal_id" identity:userId priority:1]; [Permutive.shared setIdentitiesWithAliases:@[emailAlias, idAlias] error:nil]; ``` ```swift Swift theme={"dark"} var trigger: TriggerAction? func watchCohort() { trigger = Permutive.shared.triggerProvider?.action( boolFor: ["premium_user"], action: { query, isInCohort in if isInCohort { self.showPremiumFeatures() } } ) } // Release trigger when done deinit { trigger = nil } ``` ```objectivec Objective-C theme={"dark"} // Hold strong reference @property (nonatomic, strong) PermutiveTriggerAction *trigger; - (void)watchCohort { NSSet *cohorts = [NSSet setWithObject:@"premium_user"]; self.trigger = [Permutive.shared.triggerProvider actionWithBoolFor:cohorts action:^(NSString *cohort, BOOL result) { if (result) { [self showPremiumFeatures]; } }]; } ``` ```swift Swift theme={"dark"} let adRequest = GAMRequest() adRequest.customTargeting = Permutive.shared.googleCustomTargeting( adTargetable: pageTracker ) bannerView.load(adRequest) ``` ```objectivec Objective-C theme={"dark"} GAMRequest *adRequest = [GAMRequest request]; adRequest.customTargeting = [Permutive.shared googleCustomTargetingWithAdTargetable:self.pageTracker]; [self.bannerView loadRequest:adRequest]; ``` ## Requirements | Requirement | Version | | ----------- | ------- | | iOS | 12.0+ | | tvOS | 12.0+ | | Xcode | 13.0+ | | Swift | 5.0+ | Add the package URL in Xcode: ``` https://github.com/permutive-engineering/permutive-ios-spm ``` Select `Permutive_iOS` as the package product. ```ruby theme={"dark"} target 'YourApp' do platform :ios, '12.0' pod 'Permutive_iOS', '~> 2.2.0' end ``` ## Key Concepts ## Additional Resources API documentation and technical reference. * **[API Reference](https://storage.googleapis.com/permutive-ios-refdocs/html/index.html)** - Complete API documentation * **[Apple Privacy Information](/sdks/mobile/ios/integrations/idfa-provider#apple-privacy)** - App Store privacy requirements **tvOS Differences:** The tvOS SDK shares the same API as iOS, with the following exceptions: * IDFA/App Tracking Transparency is not available on tvOS * UI patterns use focus-based navigation instead of touch ## FAQ **PageTracker** is the recommended approach for most use cases. It automatically tracks Pageview events, measures engagement time, and enables contextual cohorts when URLs are provided. **Direct event tracking** via `track(event:properties:)` is for specialized cases where you need to track custom events that don't fit the page model. Enable logging in your initialization options: ```swift theme={"dark"} let options = Options( apiKey: "", organisationId: "" ) options.logModes = LogMode.all ``` Messages will appear in the Xcode console. Use hashed emails (SHA-256), internal user IDs, or the vendor identifier (`identifierForVendor`). Never send plain text PII. See the [Identity Management](/sdks/mobile/ios/core-concepts/identity-management) guide for details. Permutive recommends against using IDFA due to Apple's App Tracking Transparency requirements. Consider using `identifierForVendor` or hashed email addresses instead. See the [IDFA Provider](/sdks/mobile/ios/integrations/idfa-provider) guide if you do need IDFA. ## Getting Help * **[Troubleshooting Guide](/sdks/mobile/ios/troubleshooting/common-errors)** - Solutions to common issues * **Customer Success Manager (CSM)** - For enabling features and exploring use cases * **[Technical Services](mailto:technical-services@permutive.com)** - For technical setup and configuration * **[Support](mailto:support@permutive.com)** - For troubleshooting and help ## Privacy & Compliance Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage. # Release Notes Source: https://docs.permutive.com/sdks/mobile/ios/release-notes/index iOS SDK updates and announcements * Fixes memory accumulation from user state and reduces unnecessary CoreData writes **(Fix)** * Config-driven automatic ID collection **(New)** * Defaults to the Core Engine when no A/B test configuration applies **(Fix)** * Persists Core Engine state in file storage instead of UserDefaults to fit within the tvOS UserDefaults size limit **(Fix)** * Improves Core Engine state persistence for workspaces with large query sets **(Fix)** * Fixes Core Data memory accumulation with large query sets **(Fix)** * Include contextual cohorts in classification model inputs **(Update)** * Adds native cohort evaluation to replace JavaScript evaluation **(New)** * Fixes race condition in third-party data refresh during startup **(Fix)** * Fixes duplicate audience matching API calls **(Fix)** * Fixes duplicate geoIP calls on SDK startup **(Fix)** * Adds support for contextual cohorts and enrichment using the new contextual data platform **(New)** * Adds caching to reduce load when fetching activations for appending to Google Ad Manager ad requests **(Update)** * Resolves a crash in CoreData due to conflicting fetchRequests **(Fix)** * Reduces the number of events being persisted on device by aggregating SegmentEntry and Exit events into PageViewComplete **(Update)** * Add a configuration option to disable low memory mode **(Update)** * Drops support for iOS 11. iOS 12 is now the minimum version supported **(Update)** * Update privacy manifest UserDefaults key **(Fix)** * Update privacy manifest to include UserDefaults usage **(Update)** * Add privacy manifest to bundle **(New)** * Fixed an issue where the SDK would repeatedly retry some network calls if the connection was blocked **(Fix)** * Fixed issue with Classification Model configuration options **(Fix)** * Updated API to retrieve activations **(New)** * Updated API to retrieve cohorts, including classification models if supported **(New)** * Updated trigger action API to return as String type rather than Int **(Update)** * Added support for classification models **(New)** Please reach out to your CSM if you wish to enable this feature * Deprecated segments property **(Deprecation)** * Deprecated reactions property **(Deprecation)** * API to identify a user with the IDFA tag and UUID **(New)** * Fixed an issue where writing to standard defaults can cause a crash in certain cases **(Fix)** * Updates MediaTracker video event names to drop CTV prefix **(Update)** * Improved developer logging **(New)** * Fixed an issue which allowed event tracking before ready **(Fix)** * API to expose current user ID **(New)** * API offering setting Alias priority and expiry for use with identity calls **(New)** * Addition allow event enrichment with IBM Watson **(New)** * Addition to integrate use of Third Party Data when activated **(New)** * Fixed an issue which could cause Core Data crash **(Fix)** * Fixed an issue which used invalid bundle version information **(Fix)** * Performance improvements and bug fixes **(Fix)** * Addition of video tracking support **(New)** * Addition of GAM helper API **(New)** * Production v1 release * Improved PageTracker API **(Fix)** * PageTracker refreshes session expiry **(Fix)** * Improved PageTracker concurrency handling **(Fix)** * Prevent tracking of events with empty names **(Fix)** * Moved identity addition to SDK queue **(Fix)** * Aliases published on SDK start **(Update)** * Metric tracking duration fix for identity and PageTracker **(Fix)** * User settings load after persistence initialisation **(Fix)** * Addition of State Sync feature **(New)** * Addition of Identity feature **(New)** * Fix an issue converting Ints to Booleans in EventProperties **(Fix)** * Fix Metric schema issue **(Fix)** * Make error thrown from Permutive API more informative **(Update)** * Fix call stack used with SDK errors **(Fix)** * Fix to allow partial connection information use **(Fix)** * PageTracker inherits from NSObject to allow strong references **(Fix)** * Fix an issue with ABI stability affecting some users **(Fix)** * Added support for PageView Engagement **(New)** * Added support for Metric Persistency **(New)** * Restoration of all user data from persistence **(Fix)** * Addition of canary deployment feature **(New)** * Renaming of SDK Error class **(Fix)** * High CPU usage bug fix **(Fix)** * Addition of SDK reset API **(New)** * Removal of persistent data of previous alpha SDK on start **(New)** * Event schema errors reported in SDK log **(New)** * SDK persists session **(New)** * Simplified EdgeProcessor logic **(Update)** * Change of Context API **(Update)** * Updated PageTracker API naming **(Update)** * API Added documentation **(New)** * Addition Background awareness **(New)** Allows tracking of activity in background for better performances. * Addition CoreData Migration **(New)** Allows upgrading of Data Model without reinstalling the application. * Addition of PageView Tracking **(New)** Allows tracking of a PageView and PageViewComplete. * Addition of Lookalike model **(New)** * Addition of Mac Catalyst support **(New)** Allows support of OS X platform. * API typo fix **(Fix)** * API to return SDK version **(New)** Allows SDK users to interrogate SDK for version. * Addition of tvOS platform **(New)** Allows release of a tvOS compatible SDK. * Addition of tvOS integration test target **(New)** Allow running integration tests on tvOS simulator as XCTest target. * Addition of tvOS integration app **(New)** Allows running integration tests on tvOS devices. * Deactivates SDK on low system memory **(Fix)** # Common Issues Source: https://docs.permutive.com/sdks/mobile/ios/troubleshooting/common-errors Solutions to common Permutive iOS SDK problems This guide covers common issues and their solutions when integrating the Permutive iOS SDK. ## Installation Issues **Error:** `Unable to find a specification for 'Permutive_iOS'` **Solutions:** 1. Update your CocoaPods repo: ```bash theme={"dark"} pod repo update ``` 2. Ensure CocoaPods is version 1.9.1 or later: ```bash theme={"dark"} pod --version ``` 3. Clear the cache: ```bash theme={"dark"} pod cache clean --all pod install ``` **Error:** Xcode cannot resolve the package. **Solutions:** 1. Check your network connection 2. Reset package caches: **File → Packages → Reset Package Caches** 3. Verify the URL is correct: `https://github.com/permutive-engineering/permutive-ios-spm` 4. Try removing and re-adding the package **Error:** `No such module 'Permutive_iOS'` **Solutions:** 1. Clean build folder: **Product → Clean Build Folder** (⇧⌘K) 2. For CocoaPods: Ensure you opened the `.xcworkspace` file, not `.xcodeproj` 3. Restart Xcode 4. For SPM: Reset package caches **Error:** Bitcode-related build errors. **Solution:** Disable Bitcode in your target's Build Settings: * Set **Enable Bitcode** to **No** Bitcode is no longer required for App Store submission. **Error:** Duplicate symbol errors during linking. **Solutions:** 1. Ensure you're not mixing CocoaPods and SPM for Permutive 2. Check for conflicting library versions 3. Clean derived data: `rm -rf ~/Library/Developer/Xcode/DerivedData` ## Initialization Issues **Problem:** `Options(apiKey:organisationId:workspaceId:)` returns nil. **Causes:** * Empty or whitespace-only credentials * Invalid credential format **Solution:** Verify your credentials: ```swift theme={"dark"} let apiKey = "".trimmingCharacters(in: .whitespacesAndNewlines) let orgId = "".trimmingCharacters(in: .whitespacesAndNewlines) let workspaceId = "".trimmingCharacters(in: .whitespacesAndNewlines) guard !apiKey.isEmpty, !orgId.isEmpty, !workspaceId.isEmpty else { print("Credentials are empty") return } guard let options = Options(apiKey: apiKey, organisationId: orgId, workspaceId: workspaceId) else { print("Invalid credential format") return } ``` **Problem:** No error, but SDK doesn't seem to work. **Solution:** Enable debug logging and check for errors: ```swift theme={"dark"} options.logModes = LogMode.all Permutive.shared.start(with: options) { error in if let error = error { print("Initialization failed: \(error)") } else { print("SDK initialized successfully") } } ``` **Problem:** Initialization fails with network error. **Solutions:** 1. Check device network connectivity 2. Verify no firewall is blocking Permutive domains 3. Check if running on simulator with network issues 4. Retry initialization: ```swift theme={"dark"} Permutive.shared.start(with: options) { error in if error != nil { // Retry after delay DispatchQueue.main.asyncAfter(deadline: .now() + 2) { Permutive.shared.start(with: options, completion: nil) } } } ``` **Problem:** Events tracked before initialization completes are lost. **Solution:** Wait for the completion callback: ```swift theme={"dark"} Permutive.shared.start(with: options) { error in guard error == nil else { return } // Now safe to track self.startTracking() } ``` ## Tracking Issues **Error:** ``` Permutive: [error] Schema validation failed with reason(s): [#: extraneous key [invalid_key] is not permitted] ``` **Causes:** * Property names don't match schema * Property types don't match schema * Extra properties not in schema **Solutions:** 1. Check your Permutive dashboard for the correct schema 2. Verify property names exactly (case-sensitive) 3. Remove any extra properties 4. Verify property types match (string, int, bool, etc.) **Error:** `EventProperties` constructor throws an exception. **Causes:** * Unsupported value types * Invalid nested objects **Solutions:** Ensure all values are supported types: ```swift theme={"dark"} // Supported types: // String, Int, Float, Double, Bool, Date, EventProperties, and arrays of these // ❌ Wrong - Custom object let props = try EventProperties(["user": myUserObject]) // ✅ Correct - Primitive types let props = try EventProperties([ "user_id": user.id, // String "user_name": user.name, // String "age": user.age // Int ]) ``` **Problem:** No Pageview event in logs. **Solutions:** 1. Ensure `resume()` is called: ```swift theme={"dark"} override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) try? pageTracker?.resume() // Must call this } ``` 2. Check PageTracker was created successfully 3. Verify SDK is initialized before creating PageTracker 4. Enable debug logging **Problem:** PageTracker stops when navigating or creating new trackers. **Cause:** Only one PageTracker/MediaTracker can be active at a time. **Solution:** This is expected behavior. Creating a new tracker stops any existing one. Design your flow accordingly. **Problem:** Console is silent, no Permutive logs appear. **Solutions:** 1. Confirm `logModes` is set before `start()`: ```swift theme={"dark"} options.logModes = LogMode.all // Must set before start() Permutive.shared.start(with: options) { ... } ``` 2. Check Xcode console filter isn't hiding messages 3. Verify SDK is actually being initialized ## Cohort and Activation Issues **Problem:** `Permutive.shared.cohorts` returns an empty set. **Causes:** * SDK just initialized (cohorts not yet synced) * No events tracked yet * User doesn't qualify for any cohorts **Solutions:** 1. Wait a few seconds after initialization 2. Track some events to generate data 3. Use TriggerProvider for reactive updates 4. Check your dashboard for cohort definitions **Problem:** User is in a cohort but it doesn't appear in activations. **Cause:** Not all cohorts are activated for all platforms. **Solution:** Check your Permutive dashboard configuration. Activations must be explicitly configured for each platform (GAM, Xandr, etc.). **Problem:** `dfp_contextual` or `appnexus_adserver_contextual` is empty. **Solutions:** 1. Verify contextual features are enabled (contact your CSM) 2. Update to SDK 2.0.0+ 3. Ensure PageTracker has a valid, publicly accessible URL 4. Allow time for content analysis (1-2 seconds) 5. Check debug logs for classification errors ## Identity Issues **Error:** `setIdentityForIDFA` throws an error. **Cause:** IDFA is all zeros (tracking denied/restricted). **Solution:** ```swift theme={"dark"} if #available(iOS 14, *) { let status = ATTrackingManager.trackingAuthorizationStatus guard status == .authorized else { // Use alternative identity return } } let idfa = ASIdentifierManager.shared().advertisingIdentifier guard idfa != UUID(uuidString: "00000000-0000-0000-0000-000000000000") else { // IDFA not available return } try Permutive.shared.setIdentityForIDFA(idfa) ``` **Problem:** Alias with certain tags is ignored. **Cause:** Reserved tags: `appnexus`, `amp`, `gigya`, `sailthru`, `aaid` **Solution:** Use custom tag names: ```swift theme={"dark"} // ❌ Wrong Alias(tag: "appnexus", identity: id) // Reserved, will be ignored // ✅ Correct Alias(tag: "my_appnexus_id", identity: id) ``` **Problem:** Same user appears as different users on different devices. **Solution:** Use consistent identifiers that work across devices: ```swift theme={"dark"} // Best: Hashed email (works across all devices) Alias(tag: "email_sha256", identity: hashedEmail, priority: 0) // Good: Your internal user ID Alias(tag: "internal_id", identity: userId, priority: 1) ``` ## Ad Integration Issues **Problem:** `googleCustomTargeting` returns empty or minimal data. **Solutions:** 1. Verify SDK is initialized before calling 2. Check that cohorts exist for the user 3. Wait for cohort data to sync after initialization 4. Enable debug logging to see activations **Problem:** `prmtvvid` key not in targeting dictionary. **Solution:** Pass the active PageTracker: ```swift theme={"dark"} // ❌ Wrong - no view ID Permutive.shared.googleCustomTargeting(adTargetable: nil) // ✅ Correct - includes view ID Permutive.shared.googleCustomTargeting(adTargetable: pageTracker) ``` ## TriggerProvider Issues **Problem:** No callbacks when cohort membership changes. **Solutions:** 1. Store a strong reference to TriggerAction: ```swift theme={"dark"} class MyController { // Store as property, not local variable private var trigger: TriggerAction? func setup() { trigger = Permutive.shared.triggerProvider?.action(...) } } ``` 2. Verify cohort IDs match your dashboard exactly 3. Enable debug logging to see cohort updates **Problem:** Trigger worked initially but stopped. **Cause:** TriggerAction reference was released. **Solution:** Keep TriggerAction as an instance property for the lifetime you need it. ## Debug Logging Enable comprehensive logging for troubleshooting: ```swift theme={"dark"} guard let options = Options( apiKey: "", organisationId: "", workspaceId: "" ) else { return } // Enable all logging options.logModes = LogMode.all Permutive.shared.start(with: options) { error in // Check console for detailed logs } ``` ### Log Messages to Look For | Message | Meaning | | -------------------------- | ------------------------- | | `SDK ready` | Initialization successful | | `Accepted: X / X` | Events sent successfully | | `event rejection` | Schema validation failed | | `Schema validation failed` | Property mismatch | Always disable debug logging in production builds to avoid performance overhead. ```swift theme={"dark"} #if DEBUG options.logModes = LogMode.all #else options.logModes = LogMode.none #endif ``` ## Getting Help If you can't resolve an issue: 1. **Enable debug logging** and capture relevant logs 2. **Check SDK version** - ensure you're on the latest 3. **Contact support:** * [Support](mailto:support@permutive.com) Include in your support request: * SDK version * iOS/tvOS version * Xcode version * Relevant logs * Steps to reproduce ## Related Documentation Setup troubleshooting Configuration options Verify your integration Schema requirements # React Native Source: https://docs.permutive.com/sdks/mobile/react-native Use Permutive native Android and iOS SDKs from within your React Native application ## Overview Permutive does not provide an official React Native library, but you can utilise our native Android and iOS SDKs from within your React Native application. This involves creating Android and iOS Native Modules for communicating from JS to our Native SDKs. The full guide from React Native can be found [here](https://reactnative.dev/docs/legacy/native-modules-intro). The functions in the modules created for both platforms must share equivalent function signatures to allow the JS code to call a single function which will work on both platforms. ## Android Native Module The Android Native Module uses our native Android SDK, the full documentation for this can be found [here](/sdks/mobile/android/overview). It's recommended to use Android Studio for developing the Android native parts of your React Native application. It provides code syntax feedback, errors and code completion making it much easier to write your Android code. You can download the latest version [here](https://developer.android.com/studio). Start by importing the project into Android Studio from your `android/app` folder. ### Add the Permutive Dependency To start with, add the Permutive dependency to your Android app module in your React Native project. To do this add the dependency to the `build.gradle` which you can find in the `android/app` folder in your project. ```kotlin theme={"dark"} dependencies { // ... implementation("com.permutive.android:core:") // ... } ``` ### Create the Permutive Native Module file Then create a native module for Permutive in the Android app source code, this should be at `android/app/src/main/java//`. In this example the file is called `PermutiveModule.kt`. This file provides the bridging between the JS functions and the Native Android functions. It extends `ReactContextBaseJavaModule`. Each function you would like to expose in JS must be annotated with `@ReactMethod`. The bridging code can only return and receive specific types when interfacing with JS, for full details see the React Native official documentation for Android Native Modules [here](https://reactnative.dev/docs/legacy/native-modules-android). The following sample code demonstrates a Native Module which exposes a subset of the Permutive SDK functionality to JS: ```kotlin PermutiveModule.kt theme={"dark"} package com.permutive.reactnativesample import android.net.Uri import com.facebook.react.bridge.Arguments import com.facebook.react.bridge.Callback import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.bridge.ReactContextBaseJavaModule import com.facebook.react.bridge.ReactMethod import com.facebook.react.bridge.ReadableMap import com.facebook.react.bridge.WritableArray import com.facebook.react.bridge.WritableMap import com.permutive.android.EventProperties import com.permutive.android.PageTracker import com.permutive.android.Permutive import java.util.UUID class PermutiveModule( private val reactContext: ReactApplicationContext ) : ReactContextBaseJavaModule(reactContext) { override fun getName(): String = "PermutiveModule" private lateinit var permutive: Permutive private var pageTracker: PageTracker? = null @ReactMethod(isBlockingSynchronousMethod = true) fun initializePermutive( workspaceId: String, apiKey: String, ) { permutive = Permutive( context = reactContext, workspaceId = UUID.fromString(workspaceId), apiKey = UUID.fromString(apiKey), ) } @ReactMethod fun trackPageView( title: String?, url: String?, referrer: String?, eventProperties: ReadableMap? ) { pageTracker = permutive.trackPage( title = title, url = url?.let { Uri.parse(it) }, referrer = referrer?.let { Uri.parse(it) }, eventProperties = eventProperties?.let { EventProperties.from( *it.toHashMap().map { (k, v) -> k to v }.toTypedArray() ) } ) } @ReactMethod fun trackPageviewComplete() { pageTracker?.close() } @ReactMethod(isBlockingSynchronousMethod = true) fun currentCohorts(): WritableArray { val array = Arguments.createArray() permutive.currentCohorts.forEach { array.pushString(it) } return array } @ReactMethod(isBlockingSynchronousMethod = true) fun currentActivations(): WritableMap { val map = Arguments.createMap() permutive.currentActivations.forEach { (activationId, cohorts) -> val array = Arguments.createArray() cohorts.forEach { array.pushString(it) } map.putArray(activationId, array) } return map } @ReactMethod fun listenForCohortUpdates(callback: Callback) { permutive.triggersProvider().cohorts { cohorts -> val array = Arguments.createArray() cohorts.forEach { array.pushString(it) } callback.invoke(array) } } } ``` ### Register the Native Module On Android you need to register the Native Module with the Android application to allow the JS code to call it. To do this create a `ReactPackage` for your application where you can add your new Native Module. First create a file in your `android/app/src/main/java//` folder, in this example it's called `PermutiveAppPackage.kt`. Create a class which extends `ReactPackage` and override the `createNativeModules` method and add your Native Module to the list returned by the function. The following sample code demonstrates this: ```kotlin PermutiveAppPackage.kt theme={"dark"} package com.permutive.reactnativesample import android.view.View import com.facebook.react.ReactPackage import com.facebook.react.bridge.NativeModule import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.uimanager.ReactShadowNode import com.facebook.react.uimanager.ViewManager class PermutiveAppPackage : ReactPackage { override fun createViewManagers( reactContext: ReactApplicationContext ): MutableList>> = mutableListOf() override fun createNativeModules( reactContext: ReactApplicationContext ): MutableList = listOf(PermutiveModule(reactContext)).toMutableList() } ``` You then need to add this package to the list of packages returned by the `ReactNativeHost`'s `getPackages` function. This can be found in the `MainApplication` file in your `android/app/src/main/java//` folder. The following sample code shows this: ```kotlin MainApplication.kt theme={"dark"} package com.permutive.reactnativesample // ... class MainApplication : Application(), ReactApplication { override val reactNativeHost: ReactNativeHost = ReactNativeHostWrapper( this, object : DefaultReactNativeHost(this) { override fun getPackages(): List { // Packages that cannot be autolinked yet can be added manually here, for example: // packages.add(new MyReactNativePackage()); return PackageList(this).packages.apply { // Add your custom package here add(PermutiveAppPackage()) } } // ... } ) // ... } ``` Your Android native code is now callable from JS! How to do this is explained in a section below. ## iOS Native Module The iOS Native Module sample uses our native iOS SDK, the full documentation for this can be found [here](/sdks/mobile/ios/overview). It's recommended to use Xcode for developing the iOS native parts of your React Native application. It provides code syntax feedback, errors and code completion making it much easier to write your iOS code. You can download the latest version [here](https://developer.apple.com/xcode/). Start by importing the iOS part of the React Native project into Xcode. The easiest way to do this is by navigating to your React Native project folder and opening the `ios/.xcworkspace` file. ### Add the Permutive dependency Add the Permutive iOS dependency to your project using Swift Package Manager. To do this, go to `File -> Add Package Dependencies`. Then enter `https://github.com/permutive-engineering/permutive-ios-spm` in the Search or Enter Package URL bar, on the top right, then select Add Package, select Package Product Permutive\_iOS and add to your React Native app Target, then select Add Package. ### Create the Native Module files This guide uses Swift files which interact with the Permutive SDK and Objective-C bridging to connect these to JS. Add a new Swift file to your project in the `ios/` folder. This should be the same name as your Android module file if you've already created that, for this sample we'll use 'PermutiveModule' again so we create `PermutiveModule.swift`. Your project should have an Objective-C bridging header file which you can find at `ios//-Bridging-Header.h`. You need to import the `ReactBridgeModule` in that file as shown here: ```objectivec -Bridging-Header.h theme={"dark"} // // Use this file to import your target's public headers that you would like to expose to Swift. // #import "React/RCTBridgeModule.h" ``` You'll also need an Objective-C file which is used to expose the Swift methods to JS. Create a new Objective-C file with the same name as your Native Module file in the `ios/` folder. In this sample that is `PermutiveModule.m`. The Swift class needs to be annotated as an Objective-C exposed class and the methods need to be annotated too. Only specific types can be used when receiving parameters and returning from functions for communicating with JS. For full details on this see the official React Native iOS Native Modules documentation [here](https://reactnative.dev/docs/native-modules-ios). This sample shows a Swift module with the equivalent functionality to the Android Native Module: ```swift PermutiveModule.swift theme={"dark"} import Foundation import Permutive_iOS @objc(PermutiveModule) class PermutiveModule: NSObject { private var pageTracker: PageTrackerProtocol? = nil @objc func initializePermutive( _ workspaceId: NSString, _ key: NSString ) { guard let options = Options( apiKey: key as String, organisationId: workspaceId as String, workspaceId: workspaceId as String ) else { print("Error creating Permutive Options") return } Permutive.shared.start(with: options) { error in guard error != nil else { return } print("Error starting Permutive: \(String(describing: error))") return } } @objc func trackPageView( _ title: NSString?, _ url: NSString?, _ referrer: NSString?, _ eventProperties: NSDictionary? ) { do { // Convert NSDictionary to EventProperties let properties = try EventProperties( (eventProperties as? [String: Any])? .compactMapValues { propertyName in propertyName as? AnyHashable }.reduce(into: [:]) { outputDictionary, inputDictionary in outputDictionary[inputDictionary.key] = inputDictionary.value } ?? [:] ) let context = (title != nil && url != nil && referrer != nil) ? Context( title: title! as String, url: URL(string: url! as String)!, referrer: URL(string: referrer! as String)! ) : nil pageTracker = try Permutive.shared.createPageTracker( properties: properties, context: context ) } catch { print("Error starting page tracker: \(String(describing: error))") } } @objc func trackPageviewComplete() { pageTracker?.stop() } @objc func currentCohorts() -> NSArray { return Array(Permutive.shared.cohorts) as NSArray } @objc func currentActivations() -> NSDictionary { return Permutive.shared.activations as NSDictionary } @objc func listenForCohortUpdates(_ callback: @escaping RCTResponseSenderBlock) { let queryRange = Array().map { queryId in String(queryId) } let action = Permutive.shared.triggerProvider?.action(boolFor: Set(queryRange)) { (_, _) in callback([Array(Permutive.shared.cohorts) as NSArray]) } } } ``` To be able to call this code from JS it requires bridging through Objective-C code. To do this within the Objective-C native module file you created before, you import the same `RCTBridgeModule` and create an `RCT_EXTERN_MODULE` interface which references your Swift class. Two Objective-C functions are used to expose the Swift methods in this example: * `RCT_EXTERN_METHOD` - Exposes an asynchronous method to JS. It takes an argument in the following form: `functionName:(Parameter1Type)parameter1InternalName :(Parameter2Type)parameter2InternalName`. * `RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD` - Exposes a synchronous method to JS. It takes arguments in the same form as `RCT_EXTERN_METHOD`. The following sample shows the Objective-C code used to expose the sample Swift class: ```objectivec PermutiveModule.m theme={"dark"} #import #import "React/RCTBridgeModule.h" @interface RCT_EXTERN_MODULE(PermutiveModule, NSObject) RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(initializePermutive:(NSString)workspaceId :(NSString)key) RCT_EXTERN_METHOD(trackPageView:(NSString)title :(NSString)url :(NSString)referrer :(NSDictionary)eventProperties) RCT_EXTERN_METHOD(trackPageviewComplete) RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(currentCohorts) RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(currentActivations) RCT_EXTERN_METHOD(listenForCohortUpdates:(RCTResponseSenderBlock)callback) @end ``` Your iOS code is now ready to be called from JS! ## Calling Native code from JS To consume your native code from JS you can create a wrapper module around your native module. Create a new JS file in your `app/` folder with the same name as your Native Module files. In this sample that is `PermutiveModule.js` with the following content: ```javascript PermutiveModule.js theme={"dark"} import {NativeModules} from 'react-native'; const {PermutiveModule} = NativeModules; export default PermutiveModule; ``` You can then import this module into your React files and call into the native functions. This sample shows calling into the `PermutiveModule` in the `useEffect` function to initialize the Permutive SDK, track a Pageview, set the latest cohorts to some state and also listen for changes: ```javascript theme={"dark"} import PermutiveModule from '../PermutiveModule' export default function HomeScreen() { const [currentCohorts, setCurrentCohorts] = useState(''); useEffect(() => { PermutiveModule.initializePermutive("e0039147-51e7-4224-a814-0e2d438aabcd", "da4d09b5-843a-4bd5-bd79-8cea7f69f730"); PermutiveModule.trackPageView("Page title", null, null, null); setCurrentCohorts(PermutiveModule.currentCohorts().join(', ')); PermutiveModule.listenForCohortUpdates((cohorts: any) => setCurrentCohorts(cohorts.join(', '))) }, []) return ( // ... ) } ``` You can utilise these functions to implement Permutive within your app. If you require more functionality you can add it by creating new functions in the React Native Modules for each platform which call the relevant Permutive SDK functions. Your React Native app is now ready to finish your Permutive integration. # Cohorts and Activations Source: https://docs.permutive.com/sdks/web/javascript-sdk/core-concepts/cohorts-and-activations Understanding user segmentation in the Permutive JavaScript SDK Cohorts are the core mechanism for user segmentation in Permutive. The SDK provides methods to check cohort membership and react to changes in real-time. ## What are Cohorts ## Cohort Types ## How Cohorts Work 1. **Events are tracked** via the SDK (pageviews, custom events, etc.) 2. **Rules are evaluated** against user behavior 3. **Users enter/exit cohorts** based on rule matching 4. **Cohorts are stored locally** in the browser 5. **Cohorts are passed to ad platforms** for targeting ``` User views sports article → Track Pageview event ↓ Permutive evaluates rules ↓ User enters "sports_enthusiast" cohort ↓ Cohort stored in localStorage ↓ Cohort passed to ad requests ``` ## Activations ### Activation Types ## Cohorts vs Activations ## Accessing Cohorts ### Get All Segments ```javascript theme={"dark"} // Get all cohorts the user belongs to permutive.segments(function(segments) { console.log('All segments:', segments); // Output: [12345, 67890, 11111, ...] }); ``` ### Get Platform-Specific Segments ```javascript theme={"dark"} // Get cohorts activated for Google Ad Manager (DFP) permutive.segments(function(segments) { console.log('DFP segments:', segments); }, 'dfp'); // Get cohorts activated for AppNexus permutive.segments(function(segments) { console.log('AppNexus segments:', segments); }, 'appnexus'); ``` ### Check Single Cohort Membership ```javascript theme={"dark"} // Check if user is in a specific cohort permutive.segment(12345, function(inCohort) { if (inCohort) { console.log('User is in cohort 12345'); showPremiumContent(); } else { console.log('User is NOT in cohort 12345'); showStandardContent(); } }); ``` ### Wait for Cohort Data Use `ready()` with the `'realtime'` stage to ensure cohort data is available: ```javascript theme={"dark"} permutive.ready(function() { // Cohort data is now available permutive.segments(function(segments) { console.log('Segments (after ready):', segments); }); }, 'realtime'); ``` ## Real-Time Triggers React to cohort changes as they happen: ```javascript theme={"dark"} // Trigger when user enters/exits a cohort permutive.trigger(12345, 'result', function(obj) { if (obj.result) { console.log('User just ENTERED cohort 12345'); } else { console.log('User just EXITED cohort 12345'); } }); ``` See [Real-Time Triggers](/sdks/web/javascript-sdk/features/real-time-triggers) for more details. ## localStorage Structure Cohorts are stored in localStorage for fast access and ad targeting: | Key | Purpose | | ------------- | ----------------------------------- | | `_psegs` | All cohorts | | `_pdfps` | Google Ad Manager (DFP) activations | | `_papns` | AppNexus activations | | `_prubicons` | Rubicon activations | | `_ppubmatics` | PubMatic activations | ```javascript theme={"dark"} // Direct localStorage access (for debugging) var allCohorts = JSON.parse(localStorage.getItem('_psegs') || '[]'); var dfpCohorts = JSON.parse(localStorage.getItem('_pdfps') || '[]'); ``` Always use the SDK methods (`segments()`, `segment()`) rather than reading localStorage directly in production code. The SDK handles synchronization and edge cases. ## Using Cohorts with Ad Platforms ### Google Ad Manager ```javascript theme={"dark"} // Using the DFP addon (automatic) permutive.addon('web', { page: { type: 'article' } }); // Targeting is set automatically // Manual targeting permutive.segments(function(segments) { googletag.cmd.push(function() { googletag.pubads().setTargeting('permutive', segments); }); }, 'dfp'); ``` ### Prebid.js Cohorts are automatically passed to Prebid via the RTD module. See [Prebid Integration](/sdks/web/javascript-sdk/integrations/prebid). ### AppNexus/Xandr ```javascript theme={"dark"} permutive.segments(function(segments) { // Use segments for AppNexus targeting apntag.setKeywords('permutive', segments); }, 'appnexus'); ``` ## Cohort Patterns ```javascript theme={"dark"} // Personalize content based on cohorts permutive.ready(function() { permutive.segment(12345, function(isPremiumUser) { if (isPremiumUser) { showPremiumLayout(); hideAds(); } }); }, 'realtime'); ``` ```javascript theme={"dark"} // Adjust paywall based on user segments permutive.segments(function(segments) { var isHighValueUser = segments.includes(54321); var isFrequentReader = segments.includes(98765); if (isHighValueUser && !isFrequentReader) { showSoftPaywall(); } }); ``` ```javascript theme={"dark"} // Use cohorts for A/B test targeting permutive.segment(11111, function(inTestGroup) { if (inTestGroup) { runExperimentVariantB(); } else { runExperimentVariantA(); } }); ``` ```javascript theme={"dark"} // Pass cohorts to analytics permutive.segments(function(segments) { analytics.identify({ permutive_cohorts: segments.slice(0, 10) // Top 10 cohorts }); }); ``` ## Event-Based Cohort Updates Cohorts update in real-time as users take actions: ```javascript theme={"dark"} // User reads an article about sports permutive.addon('web', { page: { type: 'article', article: { categories: ['sports', 'football'] } } }); // Moments later, check if they entered the sports cohort permutive.trigger(12345, 'segment', function(inSportsCohort) { if (inSportsCohort) { console.log('User just qualified for sports cohort!'); } }); ``` ## Debugging Cohorts Enable debug mode to see cohort activity: ``` ?__permutive.loggingEnabled=true ``` Console output includes: ``` [Permutive] Segments updated: [12345, 67890, ...] [Permutive] User entered segment: 12345 [Permutive] DFP segments: [12345] ``` ## Troubleshooting **Problem:** No cohorts even after tracking events. **Solutions:** * Use `ready('realtime')` to wait for data * Check that events are being tracked (debug mode) * Verify cohorts are configured in dashboard * Ensure user hasn't opted out (consent) * Allow time for cohort processing (seconds to minutes) **Problem:** Events tracked but user not in cohort. **Solutions:** * Verify cohort rules in dashboard * Check event properties match rule conditions * Confirm cohort is active (not paused/archived) * Check cohort minimum threshold/frequency **Problem:** User in cohort but activation array differs. **Solutions:** * Check that cohort is activated for the platform * Verify activation configuration in dashboard * Use correct type parameter: `segments(cb, 'dfp')` **Problem:** Cohorts not updating after new events. **Solutions:** * Cohorts update in real-time but may take a few seconds * Refresh page to trigger re-evaluation * Check that new events are actually being tracked * Use `trigger()` for real-time change detection ## Related Documentation React to cohort changes Build cohorts in dashboard Content-based cohorts GAM targeting setup # Consent Management Source: https://docs.permutive.com/sdks/web/javascript-sdk/core-concepts/consent-management Handle user consent with the Permutive JavaScript SDK The Permutive SDK provides consent mechanisms for data controllers to signal user consent status. This page covers how to implement consent handling in your web integration. ## Overview Permutive operates as a **data processor**, processing personal data on behalf of publishers who act as data controllers. Publishers are responsible for obtaining user consent and signaling that consent to Permutive. For complete information about Permutive's consent mechanisms, see the [Consent documentation](/governance/consent). ## Consent Modes Permutive provides two consent modes that publishers can configure for their deployment. ### Consent-by-Default By default, Permutive assumes the data controller has consent to track their users' data. In this configuration mode, the collection of user data starts from the first time Permutive's SDK loads without requiring a consent token. ```html theme={"dark"} ``` ### Consent-by-Token As a data controller, you may need to receive consent from the user before tracking data against them. When `consentRequired: true`, no user data is collected until the data controller has received consent from the user and passed the user's consent token to the Permutive SDK. Once the SDK has been granted consent, it will start collecting user data from this moment on. The user can revoke this consent at any point. ```html theme={"dark"} ``` No user data will be tracked by the SDK until it receives a consent token for the user. With `consentRequired: true`, events are **discarded** until consent is granted—they are not queued. ## The consent() Method ### Granting Consent Once you have obtained consent for the user, pass it to Permutive by calling the SDK `consent` method: ```javascript theme={"dark"} permutive.consent({ opt_in: true, token: "YOUR_CONSENT_TOKEN_HERE" }); ``` From this point on, the SDK will track user event data—or until the user wishes to opt out. | Parameter | Type | Description | | --------- | ------- | -------------------------------------------- | | `opt_in` | boolean | Whether user has consented | | `token` | string | Consent token (required when `opt_in: true`) | ### About the Consent Token The consent token can have **any value**. Generally, this is used if an ID gets generated when the user gives consent via a Consent Management Platform to provide some transparency, but the actual value has no meaning to Permutive. As long as `opt_in` is `true` and the `token` is not null, Permutive considers consent to be given. ```javascript theme={"dark"} // Example: Using a fixed token value permutive.consent({ opt_in: true, token: "CONSENT_CAPTURED" }); // Example: Using a CMP-generated token permutive.consent({ opt_in: true, token: cmp.getConsentId() }); ``` Some customers use a fixed value like `"CONSENT_CAPTURED"` for simplicity. Choose whatever approach works best for your consent management workflow. ## Opt Out You may choose or be required to offer users the option to opt out of tracking. All future tracking is then disabled for the user until the point they opt back in. Whether the SDK is configured in consent-by-default or consent-by-token mode, a user can be opted out by setting the consent `opt_in` field to `false`: ```javascript theme={"dark"} permutive.consent({ opt_in: false }); ``` ### What Happens on Opt Out 1. **Tracking stops** - No new events are sent 2. **State reset** - User ID and session cleared 3. **localStorage cleared** - Cohorts and identity data removed 4. **Cookies cleared** - `permutive-id` cookie deleted ### Opt Back In Users can opt back in by calling `consent()` with `opt_in: true`: ```javascript theme={"dark"} permutive.consent({ opt_in: true, token: "CONSENT_CAPTURED" }); ``` After opting out and back in, the user receives a new user ID. Their previous behavioral history is not linked to the new profile. ## CMP Integration Examples ### Generic CMP Pattern ```javascript theme={"dark"} // Check CMP consent status function handleConsent() { if (cmp.hasUserConsented()) { permutive.consent({ opt_in: true, token: cmp.getConsentToken() || "CONSENT_CAPTURED" }); } else { permutive.consent({ opt_in: false }); } } // Listen for consent changes cmp.onConsentChange(handleConsent); ``` ### OneTrust Example ```javascript theme={"dark"} function OptanonWrapper() { // Check if relevant category is consented if (OnetrustActiveGroups.includes('C0002')) { permutive.consent({ opt_in: true, token: 'onetrust_consent' }); } else { permutive.consent({ opt_in: false }); } } ``` ### Cookiebot Example ```javascript theme={"dark"} window.addEventListener('CookiebotOnAccept', function() { if (Cookiebot.consent.statistics) { permutive.consent({ opt_in: true, token: 'cookiebot_consent' }); } }); window.addEventListener('CookiebotOnDecline', function() { permutive.consent({ opt_in: false }); }); ``` ## TCF Registration For customers who must use a consent management platform that relies on the Global Vendor List (GVL), Permutive is registered on the GVL for IAB Europe's Transparency & Consent Framework (TCF). | Detail | Value | | --------------- | ------------------------------------------------------- | | **GVL ID** | 361 | | **Purpose** | Purpose 1 (store and/or access information on a device) | | **TCF Version** | 2.3 | As a data processor, Permutive primarily relies on consent obtained by the publisher through the consent mechanisms described above (`consent-by-default` or `consent-by-token`). The TCF registration is provided for customers with specific GVL requirements. ## Consent State ### Consent Persistence Consent status is stored in localStorage and persists across sessions. The SDK automatically respects the stored consent state on subsequent page loads. ### Checking Consent Status ```javascript theme={"dark"} // Consent is stored in localStorage var consentData = localStorage.getItem('permutive-consent'); if (consentData) { var consent = JSON.parse(consentData); console.log('Consent status:', consent.opt_in); } ``` ## Troubleshooting **Problem:** SDK loaded but no events appearing. **Solutions:** * Verify `consent()` is called with `opt_in: true` and a non-null `token` * [Enable debug mode](/sdks/web/javascript-sdk/getting-started/verification#debug-mode) (`?__permutive.loggingEnabled=true`) to see consent status * Check localStorage for `permutive-consent` key **Problem:** User must consent on every page load. **Solutions:** * Check localStorage is not being cleared * Verify CMP integration is consistent across pages * Ensure consent token is not null ## Related Documentation Platform consent mechanisms SDK initialization options # Contextual Data Source: https://docs.permutive.com/sdks/web/javascript-sdk/core-concepts/contextual-data Content-based real-time targeting with the Permutive JavaScript SDK Contextual targeting allows you to reach users based on the content they're currently viewing, without relying on user history or cookies. ## Overview ## Privacy Benefits ## Behavioral vs Contextual ## Implementation ### Page Properties The primary way to enable contextual targeting is through page properties: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Electric Vehicle Sales Surge in 2024', categories: ['automotive', 'electric-vehicles', 'business'], tags: ['EV', 'Tesla', 'sustainability', 'green-tech'], authors: ['Jane Smith'], publishedAt: '2024-01-15T10:00:00Z' } } }); ``` These properties are analyzed to generate contextual cohorts like: * `automotive_electric_vehicles` * `business_sustainability` * `technology_green_tech` ### Content Classifications Permutive can integrate with content classification providers for automated contextual data: ```javascript theme={"dark"} // Watson classifications are added automatically // when configured in your Permutive dashboard permutive.addon('web', { page: { type: 'article', // Watson adds categories, concepts, entities } }); ``` ```javascript theme={"dark"} // Pass your own classifications permutive.addon('web', { page: { type: 'article', classifications: { iab_categories: ['IAB19-6', 'IAB13-7'], sentiment: 'positive', topics: ['technology', 'innovation'] } } }); ``` ### URL-Based Context The SDK automatically captures URL context: ```javascript theme={"dark"} // Current URL is automatically included // https://example.com/technology/electric-vehicles/article-123 // You can also specify explicit context permutive.addon('web', { context: { url: 'https://example.com/technology/article', title: 'Article Title', referrer: document.referrer }, page: { type: 'article' } }); ``` ## Contextual Cohorts ### How They Work 1. **Page loads** with content metadata 2. **SDK sends context** to Permutive 3. **Real-time analysis** determines applicable contextual cohorts 4. **Cohorts returned** immediately (milliseconds) 5. **Ad requests** include contextual targeting ``` Page about electric vehicles loads ↓ SDK sends: categories: ['automotive', 'electric-vehicles'] ↓ Permutive returns: contextual cohort 'auto_ev_interest' ↓ Ad request includes contextual targeting ``` ### Accessing Contextual Cohorts Contextual cohorts are included in segment calls: ```javascript theme={"dark"} // Get all segments including contextual permutive.segments(function(segments) { console.log('All segments (incl. contextual):', segments); }); // Get DFP segments (includes contextual activations) permutive.segments(function(segments) { console.log('DFP segments:', segments); // Includes both behavioral and contextual }, 'dfp'); ``` ### Contextual-Only Targeting For users without behavioral data (new visitors, no consent): ```javascript theme={"dark"} // Contextual cohorts work without user consent // because they're based on content, not user history permutive.addon('web', { page: { type: 'article', article: { categories: ['finance', 'investing'] } } }); // Even without consent, contextual targeting is available ``` ## Page Property Best Practices ### Article Pages ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { // Required title: 'Article Title', categories: ['primary-category', 'secondary-category'], // Recommended tags: ['keyword1', 'keyword2', 'keyword3'], authors: ['Author Name'], publishedAt: '2024-01-15T10:00:00Z', // Optional - enhances targeting id: 'article-123', section: 'Technology', premium: false, wordCount: 1500, readTime: 7 } } }); ``` ### Video Pages ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'video', video: { title: 'Video Title', id: 'video-123', categories: ['entertainment', 'music'], duration: 180, // seconds series: 'Music Reviews', season: 2, episode: 5 } } }); ``` ### Homepage ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'homepage' } }); ``` ### Section/Category Page ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'section', section: { name: 'Technology', path: '/technology', depth: 1 } } }); ``` ## Use Cases Use contextual data to ensure ads appear alongside appropriate content: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { categories: ['news', 'politics'], // Contextual cohorts can be used for // brand safety exclusions brand_safe: true, content_rating: 'general' } } }); ``` Reach users without cookies or consent: ```javascript theme={"dark"} // Works for all users regardless of consent status permutive.addon('web', { page: { type: 'article', article: { categories: ['travel', 'europe'], // Contextual targeting doesn't require // user tracking or consent } } }); ``` Align ads with editorial content: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Best Running Shoes for 2024', categories: ['fitness', 'gear-reviews'], tags: ['running', 'shoes', 'athletics'], // Ads for running products can target // this contextual signal } } }); ``` Target based on timely content: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { categories: ['holidays', 'gift-guides'], seasonal: 'christmas', // Seasonal advertisers can target // holiday content } } }); ``` ## Combining Behavioral and Contextual The most effective targeting often combines both signals: ```javascript theme={"dark"} permutive.ready(function() { permutive.segments(function(allSegments) { // allSegments includes both: // - Behavioral cohorts (user history) // - Contextual cohorts (current page) // Use for comprehensive targeting googletag.cmd.push(function() { googletag.pubads().setTargeting('permutive', allSegments); }); }); }, 'realtime'); ``` ## Contextual Data Flow ``` ┌─────────────────┐ │ Page Load │ │ (with context) │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ SDK Captures │ │ page properties │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Permutive │ │ Classification │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Contextual │ │ Cohorts Returned│ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Ad Request │ │ (with cohorts) │ └─────────────────┘ ``` ## Troubleshooting **Problem:** Page properties set but no contextual cohorts. **Solutions:** * Verify page properties in debug mode * Check that contextual cohorts are configured in dashboard * Ensure categories match configured cohort rules * Allow a few seconds for processing **Problem:** Page classified incorrectly. **Solutions:** * Review page property values * Use more specific categories/tags * Check for conflicting signals in page data * Contact support for classification tuning **Problem:** Contextual cohorts exist but ads not targeting. **Solutions:** * Verify contextual cohorts are activated for the ad platform * Check `_pdfps` (or platform-specific key) in localStorage * Confirm ad server is reading targeting values * Test with debug mode enabled ## Related Documentation Build contextual cohorts Configure page properties Contextual targeting in GAM Content classification integrations # Event Properties Source: https://docs.permutive.com/sdks/web/javascript-sdk/core-concepts/event-properties Structure and validate event data in the Permutive JavaScript SDK Events in Permutive consist of a name and properties object. Properties provide the context and data that powers cohort building and insights. ## Event Structure Every event has a name and properties: ```javascript theme={"dark"} permutive.track('EventName', { property1: 'value', property2: 123, nested: { property3: true } }); ``` ### Automatic Properties The SDK automatically adds these properties to every event: | Property | Type | Description | | ------------------- | --------- | ------------------------------------ | | `time` | timestamp | When the event occurred | | `session_id` | string | Current session identifier | | `view_id` | string | Current pageview identifier | | `client.url` | string | Current page URL | | `client.referrer` | string | Referring URL | | `client.user_agent` | string | Browser user agent | | `client.viewport` | object | Browser viewport dimensions | | `geo_info` | object | Geographic information (server-side) | ## Property Types Permutive supports several property types: ```javascript theme={"dark"} permutive.track('Article', { title: 'Breaking News', category: 'technology', author: 'Jane Smith' }); ``` ```javascript theme={"dark"} permutive.track('Purchase', { price: 29.99, quantity: 2, discount_percentage: 10 }); ``` ```javascript theme={"dark"} permutive.track('UserAction', { is_subscriber: true, has_ad_blocker: false, accepted_cookies: true }); ``` ```javascript theme={"dark"} permutive.track('Article', { categories: ['technology', 'business', 'startups'], tags: ['AI', 'funding', 'silicon-valley'], authors: ['Jane Smith', 'John Doe'] }); ``` ```javascript theme={"dark"} permutive.track('Article', { article: { title: 'Breaking News', id: 'article-123', publishedAt: '2024-01-15T10:00:00Z' }, author: { name: 'Jane Smith', id: 'author-456' } }); ``` ```javascript theme={"dark"} permutive.track('Subscription', { start_date: '2024-01-15', expiry_date: '2025-01-15', created_at: new Date().toISOString() }); ``` Dates should be passed as ISO 8601 strings for consistent parsing. ## Standard Events The SDK defines standard event types with expected properties: ### Pageview Tracked automatically by the web addon: ```javascript theme={"dark"} // Automatic via web addon permutive.addon('web', { page: { type: 'article', article: { title: 'Article Title', categories: ['news'], authors: ['Author Name'], publishedAt: '2024-01-15' } } }); ``` ### Custom Event For non-standard tracking: ```javascript theme={"dark"} permutive.track('CustomEvent', { action: 'button_click', element_id: 'signup-button', page_section: 'header' }); ``` ## Property Naming Conventions Follow these conventions for consistent data: | Convention | Example | Notes | | ----------- | --------------- | ------------------------------- | | snake\_case | `article_title` | Preferred for custom properties | | camelCase | `articleTitle` | Also supported | | Lowercase | `category` | Use for simple properties | Property names are case-sensitive. `category` and `Category` are different properties. Be consistent across your implementation. ### Reserved Property Names Avoid these reserved property names: * `time` - Automatically set by SDK * `session_id` - Automatically set * `view_id` - Automatically set * `client` - Reserved for client context * `geo_info` - Reserved for geographic data ## Nested Properties You can nest properties up to 3 levels deep: ```javascript theme={"dark"} permutive.track('Article', { content: { article: { metadata: { word_count: 1500, read_time: 7 } } } }); ``` Deeply nested properties work in cohort building, but keep structures simple when possible for easier querying. ## Arrays Arrays are useful for multi-value properties: ```javascript theme={"dark"} permutive.track('Article', { // Array of strings categories: ['technology', 'business'], // Array of numbers related_article_ids: [123, 456, 789], // Array of objects authors: [ { name: 'Jane Smith', id: 'author-1' }, { name: 'John Doe', id: 'author-2' } ] }); ``` ### Array Limitations * Maximum 100 items per array * Array items should be of consistent type * Nested arrays are not recommended ## Page Properties vs Event Properties Set via the web addon, applied to all events on the page: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Article Title', categories: ['news'] } } }); // These page properties are included in: // - Pageview event // - PageviewEngagement events // - PageviewComplete event ``` Set per-event, specific to that event: ```javascript theme={"dark"} permutive.track('VideoPlay', { video_id: 'video-123', video_title: 'Demo Video', autoplay: false }); // These properties only apply to this event ``` ## Best Practices ```javascript theme={"dark"} // Good permutive.track('Article', { article_category: 'technology', article_author: 'Jane Smith', is_premium_content: true }); // Avoid permutive.track('Article', { cat: 'tech', auth: 'JS', prem: 1 }); ``` Use the same property names and types across all events: ```javascript theme={"dark"} // Consistent naming permutive.track('Article', { article_id: '123' }); permutive.track('VideoPlay', { video_id: '456' }); // Avoid mixing permutive.track('Article', { article_id: '123' }); permutive.track('Article', { articleId: '456' }); // Different convention! ``` Never include personally identifiable information: ```javascript theme={"dark"} // Good - use hashed or anonymized values permutive.track('Login', { user_type: 'subscriber', account_age_days: 365 }); // Never do this permutive.track('Login', { email: 'user@example.com', // PII! name: 'John Smith' // PII! }); ``` ```javascript theme={"dark"} // Good - correct types permutive.track('Purchase', { price: 29.99, // Number quantity: 2, // Number product_name: 'Widget', // String in_stock: true // Boolean }); // Avoid - incorrect types permutive.track('Purchase', { price: '29.99', // Should be number quantity: '2', // Should be number in_stock: 'true' // Should be boolean }); ``` Keep events focused with relevant properties only: ```javascript theme={"dark"} // Good - focused properties permutive.track('ArticleRead', { article_id: '123', category: 'technology', read_percentage: 75 }); // Avoid - too many properties permutive.track('ArticleRead', { article_id: '123', category: 'technology', // ... 50 more properties }); ``` ## Property Validation The SDK validates properties before sending: * Invalid property types are converted or dropped * Very long strings may be truncated * Invalid JSON structures are rejected Enable debug mode to see validation messages: ``` ?__permutive.loggingEnabled=true ``` ## Troubleshooting **Problem:** Event tracked but properties missing in dashboard. **Solutions:** * Check property names match dashboard schema * Verify property types are correct * Enable debug mode to see what's sent * Allow time for data processing **Problem:** Numbers stored as strings or vice versa. **Solutions:** * Explicitly cast types before tracking * Use `parseInt()` or `parseFloat()` for numbers * Avoid string representations of numbers **Problem:** Can't build cohorts on deeply nested properties. **Solution:** Flatten structure or limit nesting to 2 levels: ```javascript theme={"dark"} // Instead of deep nesting { a: { b: { c: { d: 'value' } } } } // Use flatter structure { a_b_c_d: 'value' } ``` ## Related Documentation Track custom events Configure page properties Build cohorts from properties Event schema documentation # Identity Management Source: https://docs.permutive.com/sdks/web/javascript-sdk/core-concepts/identity-management Track users across sessions and devices with the Permutive JavaScript SDK The Permutive SDK provides identity management to track users across sessions and connect data from multiple devices or touchpoints. ## Overview ## User ID Every user is automatically assigned a unique **user ID** by the SDK. This ID: * Is generated on first visit and persisted in a first-party cookie * Is unique to your domain (not shared across publishers) * Survives browser sessions and cookie clearing in most cases * Is used to track behavior and build cohorts ```javascript theme={"dark"} // Get the current user ID from localStorage var userId = localStorage.getItem('permutive-id'); console.log('User ID:', userId); ``` The user ID is stored in localStorage with the key `permutive-id`. It works in all browsers, including Safari and Firefox which block third-party cookies. ## Aliases ### Setting Aliases Use `permutive.identify()` to set user aliases: ```javascript theme={"dark"} // Set a single alias permutive.identify([ { tag: 'email_sha256', id: 'a1b2c3d4e5f6g7h8i9j0...' } ]); // Set multiple aliases permutive.identify([ { tag: 'email_sha256', id: 'a1b2c3d4e5f6g7h8i9j0...' }, { tag: 'internal_id', id: 'user_12345', priority: 1 }, { tag: 'subscriber_id', id: 'sub_789', priority: 2 } ]); ``` ### Identity Record Structure Each identity record has the following fields: | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------ | | `tag` | string | Yes | The type of identifier (configured in dashboard) | | `id` | string | Yes | The actual identifier value | | `priority` | number | No | Resolution priority (lower = higher priority) | | `expiry` | number | No | Expiration timestamp (Unix milliseconds) | ## Setting Identity ### Basic Usage ```javascript theme={"dark"} // When user logs in function onUserLogin(user) { permutive.identify([ { tag: 'email_sha256', id: hashSHA256(user.email) } ]); } ``` ### With Priority ```javascript theme={"dark"} // Set identities with explicit priority permutive.identify([ { tag: 'email_sha256', id: emailHash, priority: 0 }, // Highest priority { tag: 'internal_id', id: 'user_12345', priority: 1 }, { tag: 'device_id', id: 'device_abc', priority: 2 } // Lowest priority ]); ``` ### With Expiry Set an expiration time for temporary identities: ```javascript theme={"dark"} // Identity expires in 24 hours var expiryTime = Date.now() + (24 * 60 * 60 * 1000); permutive.identify([ { tag: 'session_token', id: 'session_abc123', expiry: expiryTime } ]); ``` ## Identity Resolution When you call `identify()`: ```javascript theme={"dark"} permutive.identify([ { tag: 'email_sha256', id: 'abc123...' } ]); ``` The SDK: 1. Sends the alias to Permutive servers 2. Server checks if this alias exists for another user 3. If found, user profiles are merged 4. SDK receives updated cohorts and state 5. Future events are linked to the resolved identity ## Common Identity Patterns ```javascript theme={"dark"} // Track login and set identity function handleLogin(user) { // Set identity permutive.identify([ { tag: 'email_sha256', id: hashSHA256(user.email) }, { tag: 'internal_id', id: user.id } ]); // Track login event permutive.track('Login', { method: 'email', is_new_user: user.isNew }); } ``` ```javascript theme={"dark"} // Set identity on new registration function handleRegistration(user) { permutive.identify([ { tag: 'email_sha256', id: hashSHA256(user.email) }, { tag: 'internal_id', id: user.id } ]); permutive.track('Registration', { signup_source: user.source, plan_type: user.plan }); } ``` ```javascript theme={"dark"} // Set identity from newsletter form function handleNewsletterSignup(email) { permutive.identify([ { tag: 'email_sha256', id: hashSHA256(email) } ]); permutive.track('NewsletterSignup', { list: 'daily_digest' }); } ``` ```javascript theme={"dark"} // Set identity from third-party provider (e.g., ID5, RampID) function setThirdPartyIdentity(providerId, identityValue) { permutive.identify([ { tag: providerId, id: identityValue } ]); } // Example with ID5 setThirdPartyIdentity('id5', 'ID5-abc123...'); ``` ## Hashing Requirements **Never send plain-text PII** to Permutive. Always hash email addresses and other personal identifiers before passing them to `identify()`. ### SHA-256 Hashing Email addresses should be hashed using SHA-256: ```javascript theme={"dark"} // Using Web Crypto API (modern browsers) async function hashSHA256(email) { const normalized = email.toLowerCase().trim(); const encoder = new TextEncoder(); const data = encoder.encode(normalized); const hashBuffer = await crypto.subtle.digest('SHA-256', data); const hashArray = Array.from(new Uint8Array(hashBuffer)); return hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); } // Usage hashSHA256('user@example.com').then(function(hash) { permutive.identify([ { tag: 'email_sha256', id: hash } ]); }); ``` ### Hashing Best Practices 1. **Normalize before hashing**: Lowercase and trim whitespace 2. **Use consistent algorithm**: SHA-256 is standard 3. **Hash on server if possible**: Avoids exposing raw email in client code 4. **Same hash everywhere**: Use identical normalization across all touchpoints ## Resetting Identity When a user logs out, reset their identity: ```javascript theme={"dark"} function handleLogout() { // Reset all SDK state permutive.reset(); // Or just track logout without reset // permutive.track('Logout', {}); } ``` `permutive.reset()` clears all user data including cohorts and identity. Use it when a user explicitly logs out or requests data deletion. ## Cross-Domain Identity For tracking users across multiple domains you own: ```javascript theme={"dark"} // On domain-a.com permutive.identify([ { tag: 'cross_domain_id', id: 'shared_user_123' } ]); // On domain-b.com (same identifier) permutive.identify([ { tag: 'cross_domain_id', id: 'shared_user_123' } ]); // Permutive will link the user profiles ``` Cross-domain identity requires using the same identity tag and value across both domains. Contact your Customer Success Manager to configure cross-domain tracking. ## Identity Events Listen for identity changes: ```javascript theme={"dark"} // Listen for identity resolution events permutive.on('SegmentEntry', function(event) { // User entered a new segment after identity resolution console.log('Entered segment:', event.properties.segment); }); ``` ## Troubleshooting **Problem:** User appears as new visitor on each session. **Solutions:** * Check that cookies aren't being blocked * Verify cookie domain configuration * Check for browser privacy settings (private mode) * Ensure `permutive-id` cookie exists in Application > Cookies **Problem:** Calling `identify()` but user data not connected. **Solutions:** * Verify identity tags are configured in dashboard * Check that identity values match exactly (case-sensitive) * Enable debug mode to see identify requests * Ensure SDK is initialized before calling identify **Problem:** Same person appears as multiple users. **Solutions:** * Ensure consistent identity values across touchpoints * Use same hashing algorithm everywhere * Set identity as early as possible in the session * Check priority settings if multiple identities conflict ## Related Documentation Structure event data correctly How identity affects cohort membership Identity and GDPR consent Platform identity resolution # Event Tracking Source: https://docs.permutive.com/sdks/web/javascript-sdk/features/event-tracking Track custom events with the Permutive JavaScript SDK Use `track()`, `on()`, and `once()` to track custom events and listen for SDK events. ## Tracking Events ### Basic Usage ```javascript theme={"dark"} permutive.track('EventName', { property1: 'value', property2: 123 }); ``` ### With Callback ```javascript theme={"dark"} permutive.track('Purchase', { product_id: 'SKU123', price: 29.99 }, { success: function(event) { console.log('Event tracked:', event); }, error: function(errorType, errorMsg) { console.error('Tracking failed:', errorType, errorMsg); } }); ``` ### With Beacon API Force use of the Beacon API for reliable tracking during page unload: ```javascript theme={"dark"} permutive.track('PageExit', { time_on_page: 120 }, { useBeacon: true }); ``` ## track() Method ### Signature ```javascript theme={"dark"} permutive.track(eventName, properties, options) ``` ### Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------- | | `eventName` | string | Yes | Name of the event | | `properties` | object | No | Event properties | | `options` | object | No | Tracking options | ### Options | Option | Type | Description | | ----------- | -------- | ----------------------------- | | `success` | function | Called when event is accepted | | `error` | function | Called on tracking error | | `useBeacon` | boolean | Force Beacon API usage | ### Return Value Returns a Promise that resolves with the event object: ```javascript theme={"dark"} permutive.track('MyEvent', { data: 'value' }) .then(function(event) { console.log('Tracked:', event); }) .catch(function(error) { console.error('Error:', error); }); ``` ## Event Examples ```javascript theme={"dark"} // Product view permutive.track('ProductView', { product_id: 'SKU123', product_name: 'Blue Widget', category: 'Widgets', price: 29.99, currency: 'USD' }); // Add to cart permutive.track('AddToCart', { product_id: 'SKU123', quantity: 2, cart_value: 59.98 }); // Purchase permutive.track('Purchase', { order_id: 'ORDER-456', products: [ { id: 'SKU123', quantity: 2 } ], total: 59.98, currency: 'USD', payment_method: 'credit_card' }); ``` ```javascript theme={"dark"} // Login permutive.track('Login', { method: 'email', is_new_session: true }); // Registration permutive.track('Registration', { signup_source: 'homepage_banner', plan_type: 'premium' }); // Search permutive.track('Search', { query: 'blue widgets', results_count: 42 }); // Share permutive.track('Share', { content_type: 'article', content_id: 'article-123', platform: 'twitter' }); ``` ```javascript theme={"dark"} // Button click permutive.track('ButtonClick', { button_id: 'cta-signup', button_text: 'Start Free Trial', page_section: 'hero' }); // Tab switch permutive.track('TabSwitch', { from_tab: 'overview', to_tab: 'pricing' }); // Modal view permutive.track('ModalView', { modal_name: 'newsletter-popup', trigger: 'exit_intent' }); ``` ```javascript theme={"dark"} // Subscription start permutive.track('SubscriptionStart', { plan_id: 'premium-monthly', plan_name: 'Premium', price: 9.99, billing_period: 'monthly' }); // Paywall hit permutive.track('PaywallHit', { paywall_type: 'hard', article_id: 'article-123', articles_read: 5 }); // Trial started permutive.track('TrialStarted', { trial_length_days: 14, plan_type: 'premium' }); ``` ## Event Listeners ### on() - Persistent Listener Listen for all occurrences of an event: ```javascript theme={"dark"} // Listen for all Pageview events permutive.on('Pageview', function(event, error) { if (error) { console.error('Event error:', error); return; } console.log('Pageview tracked:', event); }); // Listen for custom events permutive.on('Purchase', function(event) { analytics.trackRevenue(event.properties.total); }); ``` ### once() - Single Listener Listen for only the first occurrence: ```javascript theme={"dark"} // Listen for first Pageview only permutive.once('Pageview', function(event) { console.log('First pageview:', event); }); // Wait for SDK ready event permutive.once('permutive:ready', function() { console.log('SDK is ready'); }); ``` ### Pattern Matching Use regex to match multiple event types: ```javascript theme={"dark"} // Listen for all events starting with "Video" permutive.on(/^Video/, function(event) { console.log('Video event:', event.name, event); }); // Listen for all Purchase-related events permutive.on(/Purchase|AddToCart|Checkout/, function(event) { console.log('E-commerce event:', event.name); }); ``` ### Removing Listeners Store the listener reference to remove later: ```javascript theme={"dark"} var listener = permutive.on('Pageview', function(event) { console.log('Pageview:', event); }); // Later, remove the listener listener.remove(); ``` ## Standard Event Types The SDK defines these standard event types: | Event | Description | | -------------------- | ------------------------- | | `Pageview` | Page load (via web addon) | | `PageviewEngagement` | User engagement signals | | `PageviewComplete` | User leaves page | | `FormSubmission` | Form submitted | | `LinkClick` | Link clicked | | `Videoview` | Video playback started | | `VideoEngagement` | Video engagement signals | | `VideoCompletion` | Video completed | | `SegmentEntry` | User entered a cohort | | `SegmentExit` | User exited a cohort | Standard events (Pageview, etc.) are tracked automatically by the web addon. Use `track()` for custom events. ## SDK Events Listen for internal SDK events: ```javascript theme={"dark"} // SDK ready permutive.on('permutive:ready', function() { console.log('SDK initialized'); }); // Realtime data ready permutive.on('permutive:realtime', function() { console.log('Realtime cohort data available'); }); // SDK reset permutive.on('permutive:reset', function() { console.log('SDK state was reset'); }); // Web addon ready permutive.on('permutive:web:ready', function() { console.log('Web addon initialized'); }); ``` ## Best Practices ```javascript theme={"dark"} // Good - clear, specific names permutive.track('ArticleRead', {...}); permutive.track('NewsletterSignup', {...}); permutive.track('PremiumTrialStarted', {...}); // Avoid - vague or generic names permutive.track('Click', {...}); permutive.track('Event', {...}); permutive.track('Action', {...}); ``` ```javascript theme={"dark"} // Good - actionable properties permutive.track('Purchase', { order_id: 'ORDER-123', total: 99.99, currency: 'USD', product_count: 3, coupon_used: true }); // Avoid - too few or irrelevant properties permutive.track('Purchase', { timestamp: Date.now() // Already captured automatically }); ``` ```javascript theme={"dark"} // Good - track when action completes function onPurchaseComplete(order) { permutive.track('Purchase', { order_id: order.id, total: order.total }); } // Avoid - tracking before action completes function onCheckoutClick() { permutive.track('Purchase', {...}); // Purchase hasn't happened yet! processPayment(); } ``` Track meaningful user actions, not every interaction: ```javascript theme={"dark"} // Good - meaningful actions permutive.track('AddToCart', {...}); permutive.track('Search', {...}); // Avoid - excessive tracking permutive.track('MouseMove', {...}); permutive.track('Scroll', {...}); permutive.track('Focus', {...}); ``` ```javascript theme={"dark"} permutive.track('ImportantEvent', properties, { success: function(event) { // Event tracked successfully }, error: function(type, msg) { // Log or handle error errorLogger.log('Permutive tracking failed', type, msg); } }); ``` ## Tracking on Page Unload For events that must be tracked when the user leaves: ```javascript theme={"dark"} // Use Beacon API for reliable delivery window.addEventListener('beforeunload', function() { permutive.track('PageExit', { time_on_page: calculateTimeOnPage() }, { useBeacon: true }); }); ``` The web addon automatically tracks `PageviewComplete` on page unload, so you don't need to track basic exit events manually. ## Debugging Enable debug mode to see all tracked events: ``` ?__permutive.loggingEnabled=true ``` Console output: ``` [Permutive] Tracking: Purchase {order_id: "123", total: 99.99} [Permutive] Event accepted: 1/1 ``` ## Troubleshooting **Problem:** `track()` called but no events in dashboard. **Solutions:** * Check consent is granted (if `consentRequired: true`) * Verify SDK is initialized * Enable debug mode to see if events are accepted * Check for JavaScript errors before track call * Allow processing time (events may take minutes to appear) **Problem:** Success/error callbacks not called. **Solutions:** * Verify callback functions are defined correctly * Check for errors in callback code * Ensure SDK is loaded before tracking **Problem:** Event tracked but some properties missing. **Solutions:** * Check property names match expected schema * Verify property types are correct * Look for undefined values being passed * Check for typos in property names ## Related Documentation Structure event data Automatic pageview tracking Events power cohort membership Event schema documentation # Pageview Tracking Source: https://docs.permutive.com/sdks/web/javascript-sdk/features/pageview-tracking Track pageviews and user engagement with the Permutive JavaScript SDK The web addon provides automatic pageview tracking, engagement measurement, and standard event capture. This is the recommended way to track user activity. ## Web Addon The web addon automatically tracks: * **Pageview** - When a page loads * **PageviewEngagement** - Periodic engagement signals * **PageviewComplete** - When user leaves the page * **FormSubmission** - When forms are submitted * **LinkClick** - When links are clicked ### Basic Setup ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' } }); ``` This single call enables all automatic tracking features. ### With Page Properties ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Article Title', categories: ['news', 'technology'], authors: ['Jane Smith'], publishedAt: '2024-01-15T10:00:00Z' } } }); ``` ## Page Properties Page properties provide context about the content and are included in Pageview events. ### Standard Properties | Property | Type | Description | | -------------- | ------ | --------------------------------------------- | | `page.type` | string | Page type (article, homepage, section, video) | | `page.article` | object | Article-specific metadata | | `page.video` | object | Video-specific metadata | | `page.section` | object | Section/category metadata | ### Article Properties ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { // Identification id: 'article-123', title: 'Breaking News: Tech Advances', // Categorization categories: ['technology', 'business'], tags: ['AI', 'startups', 'innovation'], section: 'Technology', // Attribution authors: ['Jane Smith', 'John Doe'], publishedAt: '2024-01-15T10:00:00Z', modifiedAt: '2024-01-15T14:30:00Z', // Content attributes wordCount: 1500, readTime: 7, premium: false, sponsored: false } } }); ``` ### Video Properties ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'video', video: { id: 'video-456', title: 'Product Demo', duration: 180, categories: ['product', 'tutorial'], series: 'How-To Guides', season: 1, episode: 5 } } }); ``` ### Homepage ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'homepage' } }); ``` ### Section Page ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'section', section: { name: 'Technology', path: '/technology', level: 1 } } }); ``` ## Automatic Events ### Pageview Event Fired immediately when `addon('web')` is called: ```javascript theme={"dark"} // Event structure { name: 'Pageview', properties: { type: 'article', article: { title: 'Article Title', categories: ['news'] }, client: { url: 'https://example.com/article', referrer: 'https://google.com', user_agent: '...' } } } ``` ### PageviewEngagement Event Fired periodically while the user is on the page: ```javascript theme={"dark"} // Event structure { name: 'PageviewEngagement', properties: { engaged_time: 30, // seconds completion: 0.5 // scroll depth (0-1) } } ``` ### PageviewComplete Event Fired when the user leaves the page: ```javascript theme={"dark"} // Event structure { name: 'PageviewComplete', properties: { total_engaged_time: 120, completion: 0.85 } } ``` ### FormSubmission Event Fired when a form is submitted: ```javascript theme={"dark"} // Event structure { name: 'FormSubmission', properties: { form_id: 'newsletter-signup', form_name: 'Newsletter', // Form data (excluding sensitive fields) } } ``` Sensitive fields (password, credit card, etc.) are automatically excluded from FormSubmission events. ### LinkClick Event Fired for outbound link clicks: ```javascript theme={"dark"} // Event structure { name: 'LinkClick', properties: { href: 'https://external-site.com/page', text: 'Click here' } } ``` ## Engagement Configuration ### Engagement Interval Control how often PageviewEngagement events fire: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' }, eventInterval: 5000 // milliseconds (default: 5000) }); ``` ### Custom Engagement Detection Override the default engagement detection: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' }, addPageEngagementDetection: function(callback) { // Custom engagement detection // Call callback() when user is engaged document.addEventListener('mousemove', callback); document.addEventListener('scroll', callback); document.addEventListener('keypress', callback); // Return cleanup function return function() { document.removeEventListener('mousemove', callback); document.removeEventListener('scroll', callback); document.removeEventListener('keypress', callback); }; } }); ``` ### Custom Completion Logic Override the default scroll completion calculation: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' }, getPageCompletion: function() { // Custom completion calculation var scrollTop = window.pageYOffset; var docHeight = document.documentElement.scrollHeight; var winHeight = window.innerHeight; return scrollTop / (docHeight - winHeight); } }); ``` ## Context Override Override automatic context detection: ```javascript theme={"dark"} permutive.addon('web', { context: { url: 'https://example.com/canonical-url', title: 'Custom Page Title', referrer: 'https://custom-referrer.com' }, page: { type: 'article' } }); ``` ## SPA Support For Single Page Applications (React, Vue, Angular), call `permutive.addon('web', {...})` on navigation to track a new Pageview: ### Basic SPA Pattern ```javascript theme={"dark"} // Initial page load permutive.addon('web', { page: getPageProperties() }); // On navigation function navigateToNewPage() { permutive.addon('web', { page: getNewPageProperties() }); } ``` ### React Integration ```javascript theme={"dark"} import { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; function PermutiveTracker() { const location = useLocation(); useEffect(() => { // Track pageview on initial load and route changes permutive.addon('web', { page: getPageProperties(location) }); }, [location]); return null; } function getPageProperties(location) { return { type: 'article', article: { title: document.title, // ... other properties } }; } ``` ### Vue Integration ```javascript theme={"dark"} // In router/index.js or main.js import router from './router'; router.afterEach((to, from) => { // Track pageview on every navigation permutive.addon('web', { page: getPageProperties(to) }); }); function getPageProperties(route) { return { type: route.meta.pageType || 'page', // ... other properties }; } ``` ### Angular Integration ```typescript theme={"dark"} // In app.component.ts import { Router, NavigationEnd } from '@angular/router'; import { filter } from 'rxjs/operators'; @Component({...}) export class AppComponent { constructor(private router: Router) { this.router.events .pipe(filter(event => event instanceof NavigationEnd)) .subscribe((event: NavigationEnd) => { this.trackPageview(event.urlAfterRedirects); }); } private trackPageview(url: string): void { const pageProps = this.getPageProperties(url); // Track pageview on every navigation (window as any).permutive.addon('web', { page: pageProps }); } } ``` ## Infinite Scroll For infinite scroll pages, track additional content loads: ```javascript theme={"dark"} var webAddon = permutive.addon('web', { page: { type: 'feed' }, dirtyEvents: ['contentLoaded'] // Custom dirty events }); // When new content loads function onNewContentLoaded() { // Mark page as "dirty" to trigger new engagement tracking webAddon.markDirty('contentLoaded'); } ``` ## Filtering Events Filter which events are tracked: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' }, filterPermutiveEvent: { // Only track form submissions with certain IDs FormSubmission: function(event) { return event.target.id !== 'search-form'; }, // Only track external links LinkClick: function(event) { var href = event.target.href; return href && !href.includes(window.location.hostname); } } }); ``` ## Debugging Enable debug mode to see pageview tracking in action: ``` ?__permutive.loggingEnabled=true ``` Console output: ``` [Permutive] Web addon initialized [Permutive] Tracking: Pageview {type: "article", ...} [Permutive] Event accepted: 1/1 [Permutive] Tracking: PageviewEngagement {engaged_time: 5} ``` ## Troubleshooting **Problem:** No Pageview event in debug output. **Solutions:** * Verify `permutive.addon('web', {...})` is called * Check that consent is granted (if `consentRequired: true`) * Ensure SDK is loaded before addon call * Look for JavaScript errors in console **Problem:** No PageviewEngagement events. **Solutions:** * Check `eventInterval` isn't set too high * Verify user is actively engaging (scroll, mouse move) * Ensure page stays open long enough * Test with debug mode enabled **Problem:** Only first pageview tracked in SPA. **Solutions:** * Call `permutive.addon('web', { page: {...} })` on each route change * Verify the addon call receives updated page properties * Check that router events are firing correctly **Problem:** Multiple Pageview events per page. **Solutions:** * Ensure `addon('web')` called only once * Check for multiple SDK initializations * Verify not calling both addon and track manually ## Related Documentation Track custom events Structure event data Page-based targeting Track video content # Real-Time Triggers Source: https://docs.permutive.com/sdks/web/javascript-sdk/features/real-time-triggers React to cohort changes with trigger(), segment(), segments(), and query() The SDK provides methods to check cohort membership and react to changes in real-time, enabling dynamic personalization and targeting. ## Overview Real-time triggers enable: * **Personalization** based on cohort membership * **Dynamic content** that updates as users qualify for cohorts * **Conditional logic** for features, ads, and experiences * **Real-time reactions** to cohort entry and exit ## trigger() React to cohort entry and exit events in real-time. The handler fires whenever the user's membership in the specified segment changes. ### Usage ```javascript theme={"dark"} permutive.trigger(segmentCode, parameterName, handler); ``` ### Parameters | Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------ | | `segmentCode` | number | The cohort ID to watch | | `parameterName` | string | Parameter name (typically `"result"`) | | `handler` | function | Callback on segment transitions (receives object with `result` property) | ### Example ```javascript theme={"dark"} // React when user enters or exits a cohort permutive.trigger(1010, 'result', function(obj) { if (obj.result) { // User just entered the cohort showEmailSubscriptionPopup(); permutive.track('ShownEmailSubscriptionPopup', {}); } else { // User exited the cohort hideEmailSubscriptionPopup(); } }); ``` The handler receives `{ result: true }` when the user **enters** the segment and `{ result: false }` when they **exit**. For many segments (e.g., "5+ pageviews"), once a user qualifies they typically stay qualified, so you may only see the entry event. To check current membership at any time, use `permutive.segment()`. ### Trigger Patterns ```javascript theme={"dark"} // Show personalized content when user qualifies permutive.trigger(12345, 'result', function(obj) { if (obj.result) { document.getElementById('premium-section').style.display = 'block'; document.getElementById('standard-section').style.display = 'none'; } }); ``` ```javascript theme={"dark"} // Enable beta features for beta testers cohort permutive.trigger(54321, 'result', function(obj) { if (obj.result) { enableBetaFeatures(); } }); ``` ```javascript theme={"dark"} // Show targeted message when user enters cohort permutive.trigger(98765, 'result', function(obj) { if (obj.result) { showNotification('Special offer just for you!'); } }); ``` ## segment() Check if the user is in a specific cohort. ### Usage ```javascript theme={"dark"} permutive.segment(segmentCode, handler); ``` ### Parameters | Parameter | Type | Description | | ------------- | -------- | ---------------------------- | | `segmentCode` | number | The cohort ID to check | | `handler` | function | Callback with boolean result | ### Example ```javascript theme={"dark"} // Check if user is in cohort 12345 permutive.segment(12345, function(inCohort) { if (inCohort) { console.log('User is in cohort 12345'); } else { console.log('User is NOT in cohort 12345'); } }); ``` ### Promise Form ```javascript theme={"dark"} permutive.segment(12345) .then(function(inCohort) { console.log('In cohort:', inCohort); }); ``` ### Segment Patterns ```javascript theme={"dark"} // Show content based on cohort membership permutive.segment(12345, function(isPremium) { if (isPremium) { renderPremiumArticle(); } else { renderPaywall(); } }); ``` ```javascript theme={"dark"} // Use cohort for A/B test assignment permutive.segment(11111, function(inTestGroup) { if (inTestGroup) { runVariantB(); } else { runVariantA(); } }); ``` ```javascript theme={"dark"} // Tag analytics with cohort membership permutive.segment(12345, function(inCohort) { analytics.identify({ is_premium_user: inCohort }); }); ``` ## segments() Get all cohorts the user belongs to. ### Usage ```javascript theme={"dark"} permutive.segments(handler, type); ``` ### Parameters | Parameter | Type | Description | | --------- | -------- | ------------------------------------------------------------------------ | | `handler` | function | Callback with segments array | | `type` | string | Optional: 'all' (default) or platform-specific ('dfp', 'appnexus', etc.) | ### Example ```javascript theme={"dark"} // Get all segments permutive.segments(function(segments) { console.log('All segments:', segments); // Output: [12345, 67890, 11111, ...] }); // Get DFP-activated segments permutive.segments(function(segments) { console.log('DFP segments:', segments); }, 'dfp'); ``` ### Promise Form ```javascript theme={"dark"} permutive.segments() .then(function(segments) { console.log('Segments:', segments); }); ``` ### Segments Patterns ```javascript theme={"dark"} // Pass segments to ad server permutive.segments(function(segments) { googletag.cmd.push(function() { googletag.pubads().setTargeting('permutive', segments); }); }, 'dfp'); ``` ```javascript theme={"dark"} // Send segments to analytics permutive.segments(function(segments) { analytics.track('PageView', { permutive_cohorts: segments, cohort_count: segments.length }); }); ``` ```javascript theme={"dark"} // Personalize based on any matching cohort permutive.segments(function(segments) { var premiumCohorts = [12345, 67890, 11111]; var isPremium = premiumCohorts.some(function(id) { return segments.includes(id); }); if (isPremium) { showPremiumExperience(); } }); ``` ## query() Execute advanced queries against cohort data. ### Usage ```javascript theme={"dark"} permutive.query(queryCode, handler); ``` The `query()` method is reserved for future functionality and currently returns `{ result: false }`. Use `segment()` to check individual cohort membership or `segments()` to get all cohorts. ## ready() Wait for SDK initialization or realtime data before checking cohorts. ### Usage ```javascript theme={"dark"} permutive.ready(callback, stage); ``` ### Parameters | Parameter | Type | Description | | ---------- | -------- | ------------------------------------- | | `callback` | function | Called when stage is reached | | `stage` | string | 'initialised' (default) or 'realtime' | ### Example ```javascript theme={"dark"} // Wait for SDK initialization permutive.ready(function() { console.log('SDK is ready'); }); // Wait for realtime cohort data permutive.ready(function() { permutive.segments(function(segments) { // Segments are now populated console.log('Realtime segments:', segments); }); }, 'realtime'); ``` ### Stages | Stage | When Fires | | ------------- | ---------------------------------------- | | `initialised` | SDK has loaded and initialized | | `realtime` | Real-time cohort data has been processed | ### Ready Patterns ```javascript theme={"dark"} // Ensure cohort data is available permutive.ready(function() { permutive.segments(function(segments) { initializeTargeting(segments); }); }, 'realtime'); ``` ```javascript theme={"dark"} // Initialize components after SDK ready permutive.ready(function() { setupPersonalization(); initializeAnalytics(); loadAdTargeting(); }); ``` ## readyWithTimeout() If you need to delay critical actions (like ad requests) until Permutive is ready, use `readyWithTimeout` to set a maximum wait time. This ensures your page functions even if the SDK takes longer than expected to load. ### Setup First, add the `readyWithTimeout` function to your Permutive tag: ```javascript theme={"dark"} window.permutive.readyWithTimeout = function(e, i, t) { var u = !1, n = function() { u || (e(), u = !0) }; (t = t || 1/0) !== 1/0 && window.setTimeout(n, t), permutive.ready(n, i) }; ``` ### Usage ```javascript theme={"dark"} permutive.readyWithTimeout(callback, stage, timeoutMs); ``` ### Parameters | Parameter | Type | Description | | ----------- | -------- | ----------------------------------------------------------- | | `callback` | function | Called when ready or timeout is reached | | `stage` | string | 'initialised' or 'realtime' | | `timeoutMs` | number | Maximum milliseconds to wait before calling callback anyway | ### Example ```javascript theme={"dark"} // Wait up to 1500ms for realtime data, then proceed regardless window.permutive.readyWithTimeout(function() { console.log('Permutive is ready (or timed out)'); // Proceed with ad requests initializeAdRequests(); }, 'realtime', 1500); ``` Using `readyWithTimeout` is strongly recommended when delaying ad requests, as it ensures ads will still load even if there's a network issue with the Permutive SDK. ## Combining Methods ### Check Multiple Cohorts ```javascript theme={"dark"} function checkUserStatus() { var status = { isPremium: false, isEngaged: false, isNewUser: false }; var checks = 3; var complete = function() { checks--; if (checks === 0) { applyPersonalization(status); } }; permutive.segment(12345, function(result) { status.isPremium = result; complete(); }); permutive.segment(67890, function(result) { status.isEngaged = result; complete(); }); permutive.segment(11111, function(result) { status.isNewUser = result; complete(); }); } ``` ### Watch and Initial Check ```javascript theme={"dark"} // Check initial state AND watch for when segment becomes true function setupCohortTracking(cohortId, onEnter) { // Initial check permutive.segment(cohortId, function(inCohort) { if (inCohort) { onEnter(); } }); // Watch for entry (fires once when segment becomes true) permutive.trigger(cohortId, 'result', function(obj) { if (obj.result) { onEnter(); } }); } // Usage setupCohortTracking(12345, function() { showPremiumContent(); }); ``` ## Timing Considerations ### Why Use ready()? ```javascript theme={"dark"} // Without ready() - segments might be empty permutive.segments(function(segments) { console.log(segments); // Might be [] }); // With ready('realtime') - segments are populated permutive.ready(function() { permutive.segments(function(segments) { console.log(segments); // [12345, 67890, ...] }); }, 'realtime'); ``` ### Trigger Timing Triggers fire whenever segment membership changes on the current page: * `{ result: true }` when user **enters** the segment * `{ result: false }` when user **exits** the segment ```javascript theme={"dark"} // This fires on segment transitions permutive.trigger(12345, 'result', function(obj) { if (obj.result) { // User entered cohort 12345 } else { // User exited cohort 12345 } }); ``` Triggers only fire for segment transitions caused by events tracked on the current page via the `track` method. For checking a user's current cohort membership at any time, use `permutive.segment()` instead. ## Debugging Enable debug mode to see cohort activity: ``` ?__permutive.loggingEnabled=true ``` Console output: ``` [Permutive] Segments: [12345, 67890, 11111] [Permutive] User entered segment: 12345 [Permutive] User exited segment: 67890 ``` ## Troubleshooting **Problem:** No cohorts returned even though user should qualify. **Solutions:** * Use `ready('realtime')` before calling `segments()` * Verify events are being tracked * Check cohorts are configured and active in dashboard * Ensure consent is granted (if `consentRequired: true`) * Allow time for cohort processing **Problem:** Trigger callback not being called. **Solutions:** * Verify cohort ID is correct * Check that cohort rules would qualify the user * Enable debug mode to see cohort changes * Ensure SDK is initialized before setting trigger **Problem:** User should be in cohort but check returns false. **Solutions:** * Verify cohort ID matches dashboard * Check cohort is active (not paused/archived) * Ensure user meets cohort criteria * Use `ready('realtime')` to ensure data is loaded **Problem:** Cohort membership not updating. **Solutions:** * Refresh page to trigger re-evaluation * Verify new events are being tracked * Use `trigger()` with `'result'` parameter for real-time updates * Check for SDK errors in console ## Related Documentation Understanding cohort system Events that power cohorts Use cohorts for ad targeting Build cohorts in dashboard # Video Tracking Source: https://docs.permutive.com/sdks/web/javascript-sdk/features/video-tracking Track video content viewing with the Permutive JavaScript SDK using the CTV addon Track video engagement to build video-based cohorts and understand viewing behavior. ## Overview Video tracking in the Permutive JavaScript SDK is handled by the **CTV addon**. The addon manages engagement timing automatically and tracks the standard Permutive video events — `Videoview` and `VideoCompletion` — without requiring manual interval logic or custom event construction. The CTV addon is the correct approach for video tracking on: * Standard web pages with embedded video players * Web-based CTV applications (Samsung Tizen, LG WebOS, HbbTV) The CTV addon must be enabled for your project before use. Enable it in the Permutive dashboard under **Settings > Integrations**. ## Initializing the CTV Addon Initialize the addon when a user starts watching a video. Calling `permutive.addon("ctv", ...)` automatically tracks a `Videoview` event and prepares the addon for engagement tracking. ```javascript theme={"dark"} permutive.addon("ctv", { duration: 3600000, // Content duration in milliseconds videoProperties: { title: "Breaking Bad - S1E1", genre: ["Drama", "Thriller"], content_type: ["Series", "Episode"], age_rating: "TV-MA", runtime: 3600, season_number: 1, episode_number: 1, audio_language: "en", iab_categories: ["IAB1-1"] } }) ``` After initialization, the addon is available at `permutive.addons.ctv`. ### Duration Pass `duration` in **milliseconds**. This is required for the `VideoCompletion` event to include an accurate `completion` percentage. If the duration is not known at initialization time, you can set it later using `.setDuration()` before calling `.stop()`. ```javascript theme={"dark"} // Set duration later when it becomes available permutive.addons.ctv.setDuration(videoDurationMs) ``` ## Player Lifecycle Map your video player's events to the CTV addon methods. The addon handles engagement timing internally — there is no need to implement your own interval or timer logic. | Addon Method | When to Call | Effect | | :------------------ | :----------------------------------- | :-------------------------------------------------- | | `.play(position?)` | Player starts playing or user scrubs | Starts or resumes engagement timer | | `.pause(position?)` | Player pauses | Pauses engagement timer | | `.stop(position?)` | User exits or content ends | Tracks `VideoCompletion` with aggregated engagement | Positions are passed in **milliseconds**. ### Generic HTML5 Video Example ```javascript theme={"dark"} // Initialize the addon when the user starts a video permutive.addon("ctv", { duration: videoElement.duration * 1000, videoProperties: { title: "My Video Title", genre: ["Documentary"] } }) videoElement.addEventListener("play", function () { permutive.addons.ctv.play(videoElement.currentTime * 1000) }) videoElement.addEventListener("pause", function () { permutive.addons.ctv.pause(videoElement.currentTime * 1000) }) videoElement.addEventListener("ended", function () { permutive.addons.ctv.stop(videoElement.currentTime * 1000) }) ``` ### Handling Duration Not Yet Available If `duration` is not available when the video starts (common with live streams or when metadata loads asynchronously), initialize without it and call `.setDuration()` once the value is known: ```javascript theme={"dark"} videoElement.addEventListener("loadedmetadata", function () { permutive.addons.ctv.setDuration(videoElement.duration * 1000) }) ``` ### Handling Seek and Scrub When a user seeks to a new position, call `.play()` with the new position. This correctly updates the engagement tracker's reference point without inflating engaged time: ```javascript theme={"dark"} videoElement.addEventListener("seeked", function () { permutive.addons.ctv.play(videoElement.currentTime * 1000) }) ``` ### Handling Buffering Pause engagement tracking while the player is buffering so that buffer time is not counted as active engagement: ```javascript theme={"dark"} videoElement.addEventListener("waiting", function () { permutive.addons.ctv.pause() }) videoElement.addEventListener("playing", function () { permutive.addons.ctv.play(videoElement.currentTime * 1000) }) ``` ## Video Ad Tracking Track video ad events using the addon's `.track()` method. For mid-roll ads, pause the main content tracker while the ad plays and resume it when the ad finishes. ### Ad Event Reference | Event | When to Track | | :------------------ | :------------------------------- | | `VideoAdView` | When a video ad starts playing | | `VideoAdCompletion` | When a video ad finishes playing | | `VideoAdClicked` | When a user clicks on a video ad | ### Ad Event Properties Properties for video ad events are nested under the `ad` key: | Property | Type | Description | | :--------------- | :------ | :-------------------------------- | | `ad.title` | string | Title of the video advert | | `ad.duration` | number | Duration of the advert in seconds | | `ad.muted` | boolean | Whether the advert was muted | | `ad.campaign_id` | string | Campaign identifier | | `ad.creative_id` | string | Creative identifier | ### Pre-roll Ads ```javascript theme={"dark"} // Track the ad before initializing the main content const onPrerollStart = function (ad) { permutive.addons.ctv.track("VideoAdView", { ad: { title: ad.title, duration: ad.duration, campaign_id: ad.campaignId, creative_id: ad.creativeId } }) } const onPrerollEnd = function (ad) { permutive.addons.ctv.track("VideoAdCompletion", { ad: { title: ad.title, duration: ad.duration } }) // Now initialize the main content and start tracking permutive.addon("ctv", { duration: videoDurationMs, videoProperties: { title: "Show Title" } }) permutive.addons.ctv.play() } ``` ### Mid-roll Ads ```javascript theme={"dark"} const onMidrollStart = function (ad) { // Pause main content engagement tracking permutive.addons.ctv.pause() permutive.addons.ctv.track("VideoAdView", { ad: { title: ad.title, duration: ad.duration, campaign_id: ad.campaignId } }) } const onMidrollEnd = function (ad) { permutive.addons.ctv.track("VideoAdCompletion", { ad: { title: ad.title, duration: ad.duration } }) // Resume main content engagement tracking permutive.addons.ctv.play(videoElement.currentTime * 1000) } ``` ### Post-roll Ads ```javascript theme={"dark"} const onContentEnd = function () { // Complete main content tracking before post-roll permutive.addons.ctv.stop() } const onPostrollStart = function (ad) { permutive.addons.ctv.track("VideoAdView", { ad: { title: ad.title, duration: ad.duration } }) } ``` ## Video Properties Pass video metadata under the `videoProperties` key when initializing the addon. All properties are optional but richer metadata enables more precise cohort building. | Property | Type | Description | | :--------------------- | :-------- | :---------------------------------------- | | `title` | string | Video title | | `genre` | string\[] | List of genres | | `content_type` | string\[] | List of content types | | `age_rating` | string | Age rating (e.g. "PG-13", "TV-MA") | | `runtime` | number | Runtime in seconds | | `country` | string | Origin country | | `original_language` | string | Original language of the content | | `audio_language` | string | Language of the audio track being watched | | `subtitles.enabled` | boolean | Whether subtitles were enabled | | `subtitles.language` | string | Subtitle language | | `season_number` | number | Season number | | `episode_number` | number | Episode number | | `consecutive_episodes` | number | Number of episodes watched consecutively | | `iab_categories` | string\[] | IAB content taxonomy categories | Properties are type-checked by the addon. A property with the wrong type (for example, passing `audio_language` as an array instead of a string) will be silently removed from the event rather than causing a schema error. ## Complete Working Example A full integration with an HTML5 video element, including ad break handling: ```javascript theme={"dark"} var videoElement = document.getElementById("my-video") var videoDurationMs = 0 // Step 1: Capture duration when metadata loads videoElement.addEventListener("loadedmetadata", function () { videoDurationMs = videoElement.duration * 1000 }) // Step 2: Initialize the CTV addon when playback begins // This automatically tracks the Videoview event. videoElement.addEventListener("play", function () { if (!permutive.addons.ctv) { permutive.addon("ctv", { duration: videoDurationMs, videoProperties: { title: videoElement.dataset.title, genre: ["Drama"], season_number: 1, episode_number: 1, audio_language: "en" } }) } permutive.addons.ctv.play(videoElement.currentTime * 1000) }) // Step 3: Pause engagement tracking when player pauses videoElement.addEventListener("pause", function () { if (permutive.addons.ctv) { permutive.addons.ctv.pause(videoElement.currentTime * 1000) } }) // Step 4: Handle buffering videoElement.addEventListener("waiting", function () { if (permutive.addons.ctv) { permutive.addons.ctv.pause() } }) videoElement.addEventListener("playing", function () { if (permutive.addons.ctv) { permutive.addons.ctv.play(videoElement.currentTime * 1000) } }) // Step 5: Handle seeking videoElement.addEventListener("seeked", function () { if (permutive.addons.ctv) { permutive.addons.ctv.play(videoElement.currentTime * 1000) } }) // Step 6: Stop tracking when content ends (tracks VideoCompletion) videoElement.addEventListener("ended", function () { if (permutive.addons.ctv) { permutive.addons.ctv.stop(videoElement.currentTime * 1000) } }) // Ad tracking helpers function onAdStart(ad) { if (permutive.addons.ctv) { permutive.addons.ctv.pause() permutive.addons.ctv.track("VideoAdView", { ad: { title: ad.title, duration: ad.duration, campaign_id: ad.campaignId } }) } } function onAdEnd(ad) { if (permutive.addons.ctv) { permutive.addons.ctv.track("VideoAdCompletion", { ad: { title: ad.title, duration: ad.duration } }) permutive.addons.ctv.play(videoElement.currentTime * 1000) } } ``` ## Engagement Tracking Patterns The CTV addon tracks engagement automatically. You do not need to implement interval timers or milestone checks manually. The addon's internal engagement model works as follows: 1. **Play** — When `.play()` is called, the engagement clock starts. 2. **Pause** — When `.pause()` is called, the clock stops. Time elapsed since the last `.play()` call is accumulated. 3. **Resume** — When `.play()` is called again, the clock resumes from the current accumulated total. 4. **Stop** — When `.stop()` is called, the final accumulated `engaged_time` and the calculated `completion` percentage are included in the `VideoCompletion` event automatically. This means skipped content (via seeking) is never counted as engaged time, and buffering time can be excluded by calling `.pause()` during buffer states. ## Best Practices The `VideoCompletion` event is only tracked when `.stop()` is called. Make sure you call it not just when a video ends naturally, but also when a user navigates away or closes the player early. ```javascript theme={"dark"} // On natural end videoElement.addEventListener("ended", function () { permutive.addons.ctv.stop(videoElement.currentTime * 1000) }) // On user navigation / page unload window.addEventListener("beforeunload", function () { if (permutive.addons.ctv) { permutive.addons.ctv.stop() } }) ``` The `completion` percentage in `VideoCompletion` is calculated from the duration you provide. Set `duration` in milliseconds at initialization, or call `.setDuration()` once metadata is available. Do not guess or hardcode durations. ```javascript theme={"dark"} videoElement.addEventListener("loadedmetadata", function () { permutive.addons.ctv.setDuration(videoElement.duration * 1000) }) ``` Call `permutive.addon("ctv", ...)` once per piece of content. Calling it again reinitializes the addon and tracks a new `Videoview` event. If the user watches multiple videos in a session, reinitialize for each new piece of content after calling `.stop()` on the previous one. ```javascript theme={"dark"} // When moving to next video permutive.addons.ctv.stop() permutive.addon("ctv", { duration: nextVideoDurationMs, videoProperties: { title: "Next Video Title" } }) ``` Call `.pause()` when a mid-roll ad starts so that ad playback time is not included in the main content's `engaged_time`. Resume with `.play()` when the ad finishes. Every property you pass in `videoProperties` becomes available for cohort building and targeting. At minimum, include `title`. Adding `genre`, `content_type`, `season_number`, and `episode_number` significantly increases the granularity of video-based cohorts. ## Troubleshooting **Problem:** The `Videoview` event is not visible in Permutive analytics. **Solutions:** * Confirm the CTV addon is enabled under **Settings > Integrations** in the Permutive dashboard. * Verify `permutive.addon("ctv", ...)` is being called in the browser console — it should not throw an error. * Check that the SDK is initialized before `permutive.addon("ctv", ...)` is called. * Allow 5-10 minutes for events to appear in the dashboard after they fire. **Problem:** Calling `permutive.addons.ctv.play()` throws because the addon is not available. **Solutions:** * Ensure `permutive.addon("ctv", ...)` has been called before accessing `permutive.addons.ctv`. * Add a guard check: `if (permutive.addons.ctv) { ... }` before calling addon methods. * Confirm the CTV addon is enabled in your workspace settings — it will not be registered if it has not been enabled. **Problem:** The `VideoCompletion` event has a `completion` value of `0` or is missing it. **Solutions:** * Ensure `duration` is passed (in milliseconds) when calling `permutive.addon("ctv", ...)`. * If duration is not available at initialization, call `.setDuration(ms)` before `.stop()` is called. * Verify that the duration value is in milliseconds, not seconds. **Problem:** The `engaged_time` in `VideoCompletion` includes buffering or paused time. **Solutions:** * Call `.pause()` when the player enters a buffering state (`waiting` event on HTML5 video). * Call `.pause()` when the player is paused by the user. * Verify that `.pause()` is being called before ad breaks start. **Problem:** Multiple `Videoview` events fire for a single piece of content. **Solutions:** * `permutive.addon("ctv", ...)` fires a `Videoview` each time it is called. Guard the initialization so it only runs once per content session. * Use a flag or check `permutive.addons.ctv` to avoid re-initializing on repeated `play` events from the player. ## Related Documentation Video event schema and cross-platform tracking patterns Pre-built integrations for JW Player, Brightcove, YouTube, and more General event tracking with the JavaScript SDK Full CTV addon reference for web-based CTV platforms # Initialization Source: https://docs.permutive.com/sdks/web/javascript-sdk/getting-started/initialization Configure and initialize the Permutive JavaScript SDK The SDK initializes automatically when the `live.js` script loads. Configuration options are passed in the loader script and control SDK behavior. ## Basic Initialization The standard initialization passes your credentials and optional configuration: ```html theme={"dark"} ``` ## Configuration Options Pass configuration options as the fourth argument to the loader function: ```javascript theme={"dark"} !function(e,o,n,i){/* ... */}(window.permutive,"","", { // Configuration options here consentRequired: false, loggingEnabled: false }); ``` ### Available Options | Option | Type | Default | Description | | ----------------- | ------- | -------------- | ---------------------------------------------------------------------------- | | `consentRequired` | boolean | `false` | When `true`, SDK waits for consent before tracking | | `loggingEnabled` | boolean | `false` | Enable console logging (also enabled via `?__permutive.loggingEnabled=true`) | | `cookieDomain` | string | Current domain | Domain for the Permutive cookie | | `requestTimeout` | number | `5000` | API request timeout in milliseconds | ### Consent-Required Mode When `consentRequired: true`, the SDK will not track any events until consent is granted: ```html theme={"dark"} ``` With `consentRequired: true`, all tracking is blocked until `permutive.consent()` is called with `opt_in: true`. Events called before consent are not queued - they are discarded. ## Web Addon Configuration The web addon is initialized separately and handles automatic tracking. Call it after the SDK loads: ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Article Title', categories: ['news', 'technology'], authors: ['John Smith'], publishedAt: '2024-01-15T10:00:00Z' } } }); ``` ### Web Addon Options | Option | Type | Description | | --------------- | ------ | -------------------------------------------------------------- | | `page` | object | Custom page properties to include in Pageview events | | `page.type` | string | Page type (e.g., 'article', 'homepage', 'section') | | `page.article` | object | Article-specific metadata | | `page.video` | object | Video-specific metadata | | `eventInterval` | number | Milliseconds between PageviewEngagement events (default: 5000) | | `context` | object | Override default context (title, URL, referrer) | ### Page Property Examples ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Breaking News: Tech Advances', id: 'article-123', categories: ['technology', 'business'], tags: ['AI', 'startups', 'innovation'], authors: ['Jane Smith', 'John Doe'], publishedAt: '2024-01-15T10:00:00Z', modifiedAt: '2024-01-15T14:30:00Z', premium: true, wordCount: 1500 } } }); ``` ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'homepage' } }); ``` ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'section', section: { name: 'Technology', path: '/technology' } } }); ``` ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'video', video: { title: 'Product Demo', id: 'video-456', duration: 180, categories: ['product', 'tutorial'] } } }); ``` ## Waiting for SDK Ready Use `permutive.ready()` to execute code after the SDK initializes: ```javascript theme={"dark"} // Wait for SDK initialization permutive.ready(function() { console.log('Permutive SDK is ready'); // Safe to access cohorts, etc. permutive.segments(function(segments) { console.log('User cohorts:', segments); }); }); ``` ### Ready Stages The `ready()` method accepts an optional stage parameter: ```javascript theme={"dark"} // Default: Wait for basic initialization permutive.ready(function() { // SDK initialized, can track events }, 'initialised'); // Wait for real-time cohort data permutive.ready(function() { // Real-time cohort data is available permutive.segments(function(segments) { // segments array is populated }); }, 'realtime'); ``` | Stage | When Fires | | ------------- | ---------------------------------------- | | `initialised` | SDK has loaded and initialized (default) | | `realtime` | Real-time cohort data has been processed | ## Initialization Order For optimal performance, follow this initialization order: The inline loader script runs first, creating the queue and stub methods. If using `consentRequired: true`, call `permutive.consent()` after obtaining user consent. If you have user identity (e.g., logged-in user), call `permutive.identify()` early. Initialize the web addon to start tracking pageviews and engagement. Initialize other addons (DFP, Prebid, etc.) after the web addon. ### Example: Complete Initialization ```html theme={"dark"} ``` ## Cookie Configuration The SDK uses a first-party cookie to persist user identity. Configure the cookie domain for cross-subdomain tracking: ```javascript theme={"dark"} !function(e,o,n,i){/* ... */}(window.permutive,"","", { cookieDomain: '.example.com' // Shared across subdomains }); ``` Set `cookieDomain` to your root domain (with leading dot) to track users across subdomains like `www.example.com` and `blog.example.com`. ## Environment Configuration For testing environments, you may want different configurations: ```javascript theme={"dark"} var config = { loggingEnabled: window.location.hostname !== 'www.example.com' }; !function(e,o,n,i){/* ... */}(window.permutive,"","", config); ``` ## Troubleshooting Initialization **Problem:** No console messages, `permutive.ready()` callback never fires. **Solutions:** * Check that API key and workspace ID are correct * Verify `live.js` is loading (check Network tab) * Look for errors in the console * Ensure the loader script runs before `live.js` **Problem:** Events are called but nothing appears in dashboard. **Cause:** `consentRequired: true` but `consent()` was not called. **Solution:** Call `permutive.consent({ opt_in: true, token: '...' })` after obtaining user consent. **Problem:** SDK initializes but no Pageview events. **Solutions:** * Verify `permutive.addon('web', {...})` is called * Check that consent has been granted (if `consentRequired: true`) * Enable debug mode to see detailed logging **Problem:** Calling `segments()` in `ready()` callback returns empty array. **Solution:** Use the `'realtime'` stage: ```javascript theme={"dark"} permutive.ready(function() { permutive.segments(function(s) { console.log(s); // Now populated }); }, 'realtime'); ``` ## Next Steps Verify your integration is working Customize pageview tracking # Installation Source: https://docs.permutive.com/sdks/web/javascript-sdk/getting-started/installation Install the Permutive JavaScript SDK via script tag or tag manager The Permutive JavaScript SDK can be installed using several methods. Choose the approach that best fits your deployment workflow. ## Installation Methods The script tag method is the recommended approach for most websites. It provides the fastest load time and simplest setup. ### Basic Installation Add to the `` section of your page, as early as possible: ```html theme={"dark"} ``` Replace: * `` - Your [public API key](https://dash.permutive.com/settings/keys/) * `` - Your [workspace ID](https://dash.permutive.com/settings/project/) * `` - Your organization ID Place the SDK script **before** any other scripts that depend on it (like ad scripts or analytics). The SDK uses a queue-based pattern so methods can be called immediately, but the actual SDK must load before events are sent. ### With Configuration Options Pass configuration options as the fourth argument: ```html theme={"dark"} ``` Use GTM when you need to manage tags centrally without code deployments. ### Setup Steps 1. **Create a Custom HTML Tag** * Go to Tags > New > Custom HTML * Name it "Permutive SDK" 2. **Add the SDK Code** ```html theme={"dark"} ``` 3. **Create Variables** (optional but recommended) * Go to Variables > User-Defined Variables > New * Create Constant variables for API Key and Workspace ID * Reference them as `{{Permutive API Key}}` and `{{Permutive Workspace ID}}` 4. **Set the Trigger** * Use "All Pages" trigger * Set **Tag Firing Priority** to a high number (e.g., 9999) to ensure it loads first 5. **Create Web Addon Tag** ```html theme={"dark"} ``` For detailed GTM setup including Data Layer integration, see the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers). ### Tealium 1. Create a JavaScript Code extension 2. Set execution order to "Before Load Rules" 3. Add the SDK code with Tealium data layer variables ### Adobe Launch 1. Create a Core extension action for Custom Code 2. Place in the `` using the Document section 3. Set rule order to 1 (earliest execution) See the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers) for detailed instructions for each platform. ## Understanding the Loader Script The inline loader script (the first ` ``` Replace ``, ``, and `` with your credentials from the Permutive dashboard. **Queue-Based Loading:** The SDK uses a queue-based pattern. You can call SDK methods immediately - they're queued and executed once the SDK loads. ## Step 2: Initialize the Web Addon The web addon provides automatic pageview tracking, engagement measurement, and more. Add this code after the SDK script: ```html theme={"dark"} ``` Customize the `page` object with your content metadata. This enables contextual targeting and richer insights. ## Step 3: Complete Example Here's a complete example with the SDK, web addon, and page properties: ```html theme={"dark"} My Article ``` ## Step 4: Verify the Integration 1. **Enable Debug Mode**: Add `?__permutive.loggingEnabled=true` to your page URL 2. **Open Developer Console**: Press F12 or right-click and select "Inspect", then go to the Console tab 3. **Look for SDK Messages**: You should see messages like: ``` [Permutive] SDK initialized [Permutive] Pageview tracked ``` 4. **Check localStorage**: In Developer Tools, go to Application > Local Storage and look for keys starting with `permutive-` or `_p` If you see "Permutive SDK initialized" and "Pageview tracked" messages, your integration is working correctly. ## What Happens Automatically With the web addon configured, the SDK automatically: * **Tracks Pageview events** when the page loads * **Measures engagement time** (PageviewEngagement events) * **Tracks page completion** (PageviewComplete when user leaves) * **Captures form submissions** (FormSubmission events) * **Records link clicks** (LinkClick events for outbound links) ## Next Steps Tag manager options Advanced SDK configuration Customize pageview tracking Track users across sessions # Verification Source: https://docs.permutive.com/sdks/web/javascript-sdk/getting-started/verification Verify your Permutive JavaScript SDK integration is working correctly After installing the SDK, verify that events are being tracked and data is flowing correctly. For a visual, no-code way to validate your deployment, use the [Permutive Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension). It provides real-time visibility into event requests, cohort membership, ad targeting, and Prebid configuration directly in the browser. ## Quick Verification Add `?__permutive.loggingEnabled=true` to any page URL where the SDK is installed. Press F12 (or right-click > Inspect) and go to the **Console** tab. Look for messages starting with `[Permutive]`: ``` [Permutive] SDK initialized [Permutive] User ID: abc123... [Permutive] Pageview tracked ``` Log in to your Permutive dashboard and check that events appear in the Events view. ## Debug Mode Debug mode provides detailed logging of SDK activity. Enable it by adding the query parameter to your URL: ``` https://yoursite.com/page?__permutive.loggingEnabled=true ``` Or by setting `loggingEnabled: true` in the object at the end of the tag: ```html theme={"dark"} ``` ### Debug Output With debug mode enabled, you'll see console messages for: * SDK initialization status * User ID and session information * Events being tracked * Cohort/segment data * API requests and responses * Addon initialization Example debug output: ``` [Permutive] SDK initialized [Permutive] User ID: 7f8e9d0c-1b2a-3c4d-5e6f-7g8h9i0j1k2l [Permutive] Config: {apiKey: "...", workspaceId: "..."} [Permutive] Web addon initialized [Permutive] Tracking: Pageview {type: "article", ...} [Permutive] Event accepted: 1/1 [Permutive] Segments: [12345, 67890, ...] ``` ## Checking localStorage The SDK stores data in localStorage. Open Developer Tools > Application > Local Storage and look for these keys: | Key | Purpose | | ------------------- | -------------------------- | | `permutive-id` | User ID | | `permutive-consent` | Consent status | | `permutive-session` | Session data | | `_psegs` | Current segments (cohorts) | | `_pdfps` | DFP/GAM segments | | `_papns` | AppNexus segments | | `_prubicons` | Rubicon segments | Segment keys starting with `_p` contain arrays of cohort IDs that are passed to different ad platforms. ## Checking Network Requests In Developer Tools > Network tab, filter by `permutive` to see SDK requests: | Request | Purpose | | --------- | --------------- | | `live.js` | SDK script load | | `/track` | Event tracking | | `/v2.0/*` | API requests | ### Successful Event Tracking A successful track request shows: * Status: `200` or `202` * Response includes event acknowledgment ## Verification Checklist Use this checklist to verify your integration: * [ ] `permutive` object exists on `window` * [ ] `live.js` loads without errors (check Network tab) * [ ] No Content Security Policy errors in console * [ ] Debug mode shows "SDK initialized" message * [ ] `permutive-id` key exists in localStorage * [ ] User ID is consistent across page loads * [ ] If setting identity, `identify()` call completes * [ ] Pageview event fires on page load * [ ] Debug mode shows "Event accepted: 1/1" * [ ] Network tab shows successful `/track` requests * [ ] Events appear in Permutive dashboard * [ ] `_psegs` key exists in localStorage * [ ] `permutive.segments()` returns array of cohort IDs * [ ] Cohorts update after qualifying behavior * [ ] Platform-specific segment keys exist (e.g., `_pdfps` for GAM) * [ ] Ad requests include Permutive targeting * [ ] Debug mode shows addon initialization ## Console Commands Use these commands in the browser console to verify SDK state: ```javascript theme={"dark"} // Check if SDK is loaded console.log('SDK loaded:', !!window.permutive); // Get user ID console.log('User ID:', window.permutive?.user?.()); // Get current segments permutive.segments(function(segs) { console.log('All segments:', segs); }); // Get DFP segments permutive.segments(function(segs) { console.log('DFP segments:', segs); }, 'dfp'); // Check SDK readiness permutive.ready(function() { console.log('SDK is ready'); }); // Check realtime data permutive.ready(function() { console.log('Realtime data ready'); }, 'realtime'); ``` ## Common Verification Issues **Problem:** Adding `?__permutive.loggingEnabled=true` shows no messages. **Solutions:** * Verify the SDK loader script is on the page * Check that `live.js` is loading (Network tab) * Look for JavaScript errors that might block SDK * Try clearing browser cache and reloading **Problem:** Debug mode shows events accepted but nothing in dashboard. **Solutions:** * Wait a few minutes - there may be processing delay * Verify you're viewing the correct workspace * Check the event date/time filters in dashboard * Confirm API key matches the workspace **Problem:** `permutive.segments()` returns empty array. **Possible causes:** * User hasn't qualified for any cohorts yet * Real-time data hasn't loaded - use `ready('realtime')` callback * No cohorts are configured in dashboard * Consent not granted (if `consentRequired: true`) **Problem:** Different user ID on each visit. **Possible causes:** * Cookies are being blocked or cleared * Private/incognito browsing mode * Cookie domain mismatch * Third-party cookie blocking (SDK uses first-party, so this is rare) **Solution:** Check localStorage persistence and cookie settings. **Problem:** Network requests fail with CORS errors. **Solution:** This usually indicates a configuration issue. Contact support with: * Your domain * API key (first few characters) * Screenshot of the error ## Testing Specific Features ### Testing Pageview Tracking ```javascript theme={"dark"} // Check if web addon is tracking permutive.on('Pageview', function(event) { console.log('Pageview tracked:', event); }); // Manually trigger a pageview (useful for SPAs) permutive.addon('web', { page: { type: 'article' } }); ``` ### Testing Identity ```javascript theme={"dark"} // Set identity and verify permutive.identify([ { tag: 'test_id', id: 'test123' } ]); // Check it was set (after a moment) setTimeout(function() { console.log('Identity set'); }, 1000); ``` ### Testing Triggers ```javascript theme={"dark"} // Watch for segment entry permutive.trigger(12345, 'segment', function(result) { console.log('Segment trigger:', result); }); // Check segment membership permutive.segment(12345, function(inSegment) { console.log('In segment 12345:', inSegment); }); ``` ## Dashboard Verification In your Permutive dashboard: 1. **Events** - Verify events are appearing with correct properties 2. **Sources** - Check your website appears as an active source 3. **Cohorts** - Verify users are qualifying for expected cohorts 4. **Activations** - Check that cohorts are being sent to ad platforms ## Production Verification Before launching to production: * [ ] Remove any test/debug code * [ ] Verify `loggingEnabled: false` (or omitted) in production config * [ ] Test on multiple browsers (Chrome, Safari, Firefox, Edge) * [ ] Test on mobile devices * [ ] Verify consent flow works correctly (if applicable) * [ ] Check page load performance impact is acceptable * [ ] Validate ad targeting is working correctly ## Getting Help If verification fails: 1. Use the [Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension) for a visual overview of event requests, cohort membership, and ad targeting 2. Check the [Troubleshooting Guide](/sdks/web/javascript-sdk/troubleshooting/common-errors) 3. Gather debug output and network logs 4. Contact your Customer Success Manager or [technical-services@permutive.com](mailto:technical-services@permutive.com) ## Next Steps Configure pageview tracking Track custom events Set up user identity Configure ad targeting # Tag Manager Integration Source: https://docs.permutive.com/sdks/web/javascript-sdk/guides/tag-managers Deploy the Permutive JavaScript SDK via Google Tag Manager, Tealium, and Adobe Launch This guide covers deploying the Permutive SDK through popular tag management systems. ## Overview When deploying via tag manager: * **High priority execution** - Permutive should load before ad tags * **Data layer integration** - Pass page properties from your data layer * **Consistent deployment** - Use variables for credentials and properties ## Google Tag Manager ### Step 1: Create Permutive SDK Tag 1. Go to **Tags > New** 2. Click **Tag Configuration > Custom HTML** 3. Name it "Permutive SDK" 4. Add the SDK code: ```html theme={"dark"} ``` ### Step 2: Create Credential Variables 1. Go to **Variables > User-Defined Variables > New** 2. Create a **Constant** variable for API Key: * Name: `Permutive API Key` * Value: Your API key 3. Create a **Constant** variable for Workspace ID: * Name: `Permutive Workspace ID` * Value: Your workspace ID ### Step 3: Set Up Trigger 1. Under the tag, click **Triggering** 2. Select **All Pages** trigger 3. Click **Advanced Settings > Tag Firing Options** 4. Set **Tag firing priority** to `9999` (highest priority) ### Step 4: Create Web Addon Tag 1. Create another Custom HTML tag named "Permutive Web Addon" 2. Add the web addon code: ```html theme={"dark"} ``` 3. Set trigger to **All Pages** 4. Set **Tag Sequencing** to fire after "Permutive SDK" tag ### Step 5: Create Data Layer Variables Create variables to read from your data layer: 1. **Page Type** (Data Layer Variable) * Variable Name: `page.type` 2. **Page Title** (Data Layer Variable) * Variable Name: `page.title` * Or use built-in `{{Page Title}}` 3. **Page Categories** (Custom JavaScript Variable) ```javascript theme={"dark"} function() { var dl = window.dataLayer || []; for (var i = 0; i < dl.length; i++) { if (dl[i].page && dl[i].page.categories) { return dl[i].page.categories; } } return []; } ``` ### Step 6: Data Layer Setup On your website, push data to the data layer before GTM loads: ```html theme={"dark"} ``` ### Complete GTM Example **Tag 1: Permutive SDK** ```html theme={"dark"} ``` * Trigger: All Pages * Priority: 9999 **Tag 2: Permutive Web Addon** ```html theme={"dark"} ``` * Trigger: All Pages * Tag Sequencing: After "Permutive SDK" ## Tealium ### Step 1: Create JavaScript Code Extension 1. Go to **Extensions > Add Extension** 2. Select **JavaScript Code** 3. Set **Scope** to **Pre Loader** (runs before all tags) 4. Add the SDK code: ```javascript theme={"dark"} // Permutive SDK Loader !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r Add Rule** 2. Name it "Permutive SDK" 3. Under **Events**, add: * Extension: Core * Event Type: Library Loaded (Page Top) ### Step 2: Add SDK Action 1. Under **Actions**, click **Add** 2. Select: * Extension: Core * Action Type: Custom Code * Language: JavaScript 3. Check **Execute globally** 4. Add the SDK code: ```javascript theme={"dark"} // Permutive SDK !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r Add Data Element** 2. Create these data elements: * `Permutive API Key` (Constant) * `Permutive Workspace ID` (Constant) * `Permutive Organization ID` (Constant) * `Page Type` (JavaScript Variable or Custom Code) * `Page Categories` (JavaScript Variable or Custom Code) ### Step 4: Create Web Addon Rule 1. Create a new rule "Permutive Web Addon" 2. Event: DOM Ready 3. Add Custom Code action: ```javascript theme={"dark"} permutive.addon('web', { page: { type: _satellite.getVar('Page Type') || 'page', article: { title: document.title, categories: _satellite.getVar('Page Categories') || [] } } }); ``` ### Step 5: Set Rule Order 1. Set "Permutive SDK" rule order to **1** 2. Set "Permutive Web Addon" rule order to **10** ## Data Layer Best Practices ### Standardize Your Data Layer Use consistent property names across your site: ```javascript theme={"dark"} // Recommended data layer structure window.dataLayer = window.dataLayer || []; dataLayer.push({ event: 'pageview', page: { type: 'article', // article, homepage, section, video title: 'Page Title', categories: ['cat1', 'cat2'], tags: ['tag1', 'tag2'], authors: ['Author Name'] }, user: { isLoggedIn: true, hashedEmail: 'abc123...' // SHA-256 hashed } }); ``` ### Handle Identity in Tag Manager ```javascript theme={"dark"} // In a separate tag, after SDK loads if (dataLayer) { for (var i = 0; i < dataLayer.length; i++) { var data = dataLayer[i]; if (data.user && data.user.hashedEmail) { permutive.identify([ { tag: 'email_sha256', id: data.user.hashedEmail } ]); break; } } } ``` ## Troubleshooting Tag Manager Deployments **Problem:** Web addon fires before SDK loads. **Solutions:** * Use tag sequencing/ordering features * Set SDK tag priority to highest (e.g., 9999) * Use `permutive.ready()` in dependent tags **Problem:** Data layer variables return undefined. **Solutions:** * Verify data layer is populated before GTM loads * Check variable names match exactly * Use default values: `{{Variable}} || 'default'` * Debug with GTM Preview mode **Problem:** SDK sometimes loads, sometimes doesn't. **Solutions:** * Check trigger conditions * Verify no JavaScript errors blocking execution * Ensure async script loading works in your environment * Test with tag manager debug/preview mode **Problem:** Events not tracking with consent management. **Solution:** Create a consent tag that fires before web addon: ```javascript theme={"dark"} // Consent Tag (fire when CMP grants consent) permutive.consent({ opt_in: true, token: 'consent_token' }); ``` Then use tag sequencing to fire web addon after consent. ## Best Practices Never hardcode credentials directly in tags. Use tag manager variables for easy updates across environments. Always test tag firing order and variable values in the tag manager's preview mode before publishing. Keep notes on: * Tag names and purposes * Variable mappings * Data layer requirements * Firing order dependencies Use tag manager's versioning features and maintain a changelog of deployments. ## Related Documentation All installation methods Configuration options Verify your integration Consent with tag managers # Integrations Source: https://docs.permutive.com/sdks/web/javascript-sdk/integrations/overview Connect the JavaScript SDK with ad platforms and header bidding solutions The Permutive JavaScript SDK integrates with major ad platforms to enable audience targeting. For detailed setup instructions, see the main integration documentation for each platform. ## Ad Server Integrations Set up GPT targeting and key-value pairs for web Configure Xandr ad platform targeting ## Bidstream Integrations RTD module and header bidding configuration # JavaScript SDK Source: https://docs.permutive.com/sdks/web/javascript-sdk/overview Integrate Permutive into your website for user segmentation, personalization, and ad targeting ## Overview The Permutive JavaScript SDK enables user segmentation, personalization, and ad targeting on your website. Track user behavior, manage identities, and deliver targeted advertising through integrations with major ad platforms including Google Ad Manager, Prebid.js, and Xandr. **Current Version:** See your Permutive dashboard for the latest version. **Browser Support:** The SDK supports all modern browsers including Chrome, Firefox, Safari, and Edge. It is designed to work in environments without third-party cookies. ## Getting Started New to the Permutive JavaScript SDK? Start here. Get up and running with your first pageview in minutes Script tag and tag manager installation options SDK initialization and configuration options Verify your integration is working correctly ## Core Concepts Understand the fundamental concepts of the Permutive SDK. Track users across sessions and devices Structure and validate event data Understanding user segmentation Content-based real-time targeting GDPR, TCF, and consent handling ## Features Detailed guides for specific SDK features. Automatic and manual pageview tracking with the web addon Track custom events with track(), on(), and once() Track video content viewing React to cohort changes with trigger(), segment(), and query() ## Integrations Connect Permutive with ad platforms and header bidding solutions. Google Ad Manager, Prebid.js, Xandr, and more ## Common Tasks The web addon automatically tracks pageviews when configured. You can also include custom page properties. ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article', article: { title: 'Breaking News: Tech Advances', categories: ['technology', 'news'], authors: ['Jane Smith'], publishedAt: '2024-01-15' } } }); ``` ```javascript theme={"dark"} permutive.track('Purchase', { product_id: 'SKU123', product_name: 'Premium Subscription', price: 9.99, currency: 'USD' }); ``` ```javascript theme={"dark"} // Simple identity permutive.identify([ { tag: 'email_sha256', id: 'a1b2c3d4e5f6...' }, { tag: 'internal_id', id: 'user_12345', priority: 1 } ]); ``` ```javascript theme={"dark"} // Check if user is in a specific cohort permutive.segment(12345, function(inCohort) { if (inCohort) { showPremiumContent(); } }); // Get all cohorts permutive.segments(function(segments) { console.log('User cohorts:', segments); }); ``` ```javascript theme={"dark"} // Using the DFP addon (automatically sets targeting) permutive.addon('web', { page: { /* ... */ } }); // Or manually get segments for GPT permutive.segments(function(segments) { googletag.cmd.push(function() { googletag.pubads().setTargeting('permutive', segments); }); }, 'dfp'); ``` ## Key API Methods | Method | Purpose | | ----------------------------------------- | ------------------------------ | | `permutive.track(event, properties)` | Track custom events | | `permutive.identify(identities)` | Set user identities | | `permutive.trigger(code, param, handler)` | React to cohort entry/exit | | `permutive.segment(code, handler)` | Check single cohort membership | | `permutive.segments(handler, type)` | Get all cohorts | | `permutive.query(code, handler)` | Reserved for future use | | `permutive.ready(callback, stage)` | Wait for SDK initialization | | `permutive.consent(data)` | Set consent status | | `permutive.addon(name, options)` | Initialize addons | | `permutive.on(event, callback)` | Persistent event listener | | `permutive.once(event, callback)` | Single event listener | | `permutive.reset()` | Clear user data | ## Requirements | Requirement | Details | | ------------ | ----------------------------------------------------- | | Browsers | Modern browsers (Chrome, Firefox, Safari, Edge) | | JavaScript | ES5+ (SDK is transpiled for compatibility) | | Cookies | First-party cookies required for identity persistence | | localStorage | Required for cohort storage | ## Installation Add to the `` of your page, as early as possible: ```html theme={"dark"} ``` Replace ``, ``, and `` with your credentials from the Permutive dashboard. Add the Permutive tag as a high-priority tag that fires on all pages. See the [Tag Manager Guide](/sdks/web/javascript-sdk/guides/tag-managers) for GTM, Tealium, and Adobe Launch setup. ## Key Concepts The SDK uses a queue-based loading pattern. Methods called before the SDK loads are queued and executed in order once the SDK initializes. This means you can safely call SDK methods immediately without waiting for load. * **Cohorts**: All segments a user belongs to * **Activations**: Cohorts configured for specific ad platforms (e.g., `dfp` for Google Ad Manager) * **Behavioral**: Based on user history (e.g., "sports enthusiast") * **Contextual**: Based on current page content (e.g., viewing sports article right now) The `web` addon provides automatic tracking for pageviews, engagement time, form submissions, and link clicks. It's the recommended way to track user activity. ## Additional Resources * **[Tag Manager Setup](/sdks/web/javascript-sdk/guides/tag-managers)** - GTM, Tealium, Adobe Launch * **[Single Page Applications](/sdks/web/javascript-sdk/features/pageview-tracking#spa-support)** - React, Vue, Angular integration * **[Prebid Integration](/integrations/advertising/bidstream/prebid)** - RTD and Identity Manager modules * **[Consent](/governance/consent)** - Consent mechanisms and GDPR compliance ## FAQ Yes. The Permutive SDK uses first-party cookies and localStorage, which are not affected by third-party cookie restrictions. It works effectively in Safari, Firefox, and other browsers that block third-party cookies. Add `?__permutive.loggingEnabled=true` to any page URL to enable debug logging in the browser console. You'll see detailed information about events, cohorts, and SDK activity. The **web addon** automatically tracks standard events (Pageview, PageviewEngagement, FormSubmission, LinkClick) with minimal configuration. Use `track()` for custom events that don't fit these patterns. Set `consentRequired: true` in your configuration, then call `permutive.consent({ opt_in: true, token: '...' })` after obtaining user consent. See the [Consent Management](/sdks/web/javascript-sdk/core-concepts/consent-management) guide for details. Yes. Call `permutive.addon('web', { page: {...} })` on each route change to track new pageviews. See [Pageview Tracking](/sdks/web/javascript-sdk/features/pageview-tracking#spa-support) for details. ## Getting Help * **[Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension)** - Visual deployment validation and debugging * **[Troubleshooting Guide](/sdks/web/javascript-sdk/troubleshooting/common-errors)** - Solutions to common issues * **Customer Success Manager** - Your primary contact * **[Technical Services](mailto:technical-services@permutive.com)** - Technical integration support ## Privacy & Compliance Permutive is designed with privacy in mind: GDPR compliant, CCPA compliant, no PII storage, user consent respected, and transparent data usage. # Release notes Source: https://docs.permutive.com/sdks/web/javascript-sdk/release-notes/index # Changelog All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. ## @permutive/javascript-sdk 20.65.5 (2026-04-22) ### Bug Fixes * **javascript-sdk:** align stackadapt addon key with extensions platform (#3432) ## @permutive/javascript-sdk 20.65.4 (2026-04-16) ### Build System * consolidate yarn version source of truth (#3417) ## @permutive/javascript-sdk 20.65.3 (2026-04-14) ### Performance Improvements * **SlotClicked:** listen to blur and visibilitychange (#2825) ## @permutive/javascript-sdk 20.65.2 (2026-04-01) ### Bug Fixes * **dfp:** add `rts` to all segments Set (#3396) ## @permutive/javascript-sdk 20.65.1 (2026-03-27) ### Bug Fixes * **javascript-sdk:** make reset() wait for segmentation service reinitialisation (#3356) ## @permutive/javascript-sdk 20.65.0 (2026-03-18) ### Features * **equativ:** add cookie sync addon (#3316) ## @permutive/javascript-sdk 20.64.1 (2026-03-16) ### Bug Fixes * **query-language:** evaluate invalidated TPD queries (#3334) ## @permutive/javascript-sdk 20.64.0 (2026-03-12) ### Features * **javascript-sdk:** add stackadapt cookie sync addon (#3321) ## @permutive/javascript-sdk 20.63.2 (2026-03-03) ### Bug Fixes * **sdk:** add polyfills for babel runtime (#3195) ## @permutive/javascript-sdk 20.63.1 (2026-02-20) ### Reverts * **classifications:** feat(classifications): provide contextual cohorts (#3220) (#3220, #3221, #3200, #3143, #3226, #3224, #3228, #3227) ## @permutive/javascript-sdk 20.63.0 (2026-02-19) ### Features * **activations:** update block list (#3226) ## @permutive/javascript-sdk 20.62.3 (2026-02-04) ### Bug Fixes * do not await contextual data indefinitely (#3205) * regression in audience matching query processing (#3206) ## @permutive/javascript-sdk 20.62.3 (2026-02-04) ### Bug Fixes * regression in audience matching query processing (#3206) ## @permutive/javascript-sdk 20.62.2 (2026-01-29) ### Bug Fixes * **user-groups:** set api backoff call to 10 mins (#3175, #3180) ## @permutive/javascript-sdk 20.62.1 (2026-01-15) ### Bug Fixes * **javascript sdk:** report cloud lift errors (#3087) ## @permutive/javascript-sdk 20.62.0 (2026-01-15) ### Features * **Adform:** adds support for Adform ID sync (#3179) ## @permutive/javascript-sdk 20.61.9 (2026-01-13) ### Reverts * **release:** Revert "chore(release): nx release \[skip ci]" (67ef979d1) ## @permutive/javascript-sdk 20.61.8 (2026-01-12) ### Reverts * **release:** Revert "chore(release): nx release \[skip ci]" (ca95e1cf5) ## @permutive/javascript-sdk 20.61.7 (2026-01-12) ### Bug Fixes * noop (#3169) ## @permutive/javascript-sdk 20.61.5 (2026-01-09) ### Bug Fixes * noop (#3157) (f3e30da) ## @permutive/javascript-sdk 20.61.4 (2026-01-09) ### Bug Fixes * noop (#3155) (9d9916f) ## @permutive/javascript-sdk 20.61.3 (2026-01-09) ### Bug Fixes * noop (#3153) (c8fbcc8) ## @permutive/javascript-sdk 20.61.2 (2026-01-09) ### Bug Fixes * escape URL components (#3036) (45610cd) ## @permutive/javascript-sdk 20.61.1 (2026-01-05) ### Bug Fixes * **web-sdk-config:** skip curation\_platforms segment when id is missing (#3145) (dedcbf9) # @permutive/javascript-sdk 20.61.0 (2025-12-16) ### Features * **cohort-activation:** update configuration (#3129) (78ad6da) ## @permutive/javascript-sdk 20.60.1 (2025-12-15) ### Bug Fixes * **overlays:** wrap key as string (#3127) (4d2c404) # @permutive/javascript-sdk 20.60.0 (2025-12-05) ### Features * **appnexus pixel:** Add GDPR parameters to app nexus Pixel URL (#3045) (a8c037f) ## @permutive/javascript-sdk 20.59.1 (2025-12-04) ### Bug Fixes * **activations:** allow event tracking for dfp (#3103) (8db1186) # @permutive/javascript-sdk 20.59.0 (2025-12-04) ### Features * sdk config change (#3102) (bc10662) # @permutive/javascript-sdk 20.58.0 (2025-12-03) ### Features * **APS:** use ortb2 user.ext.eids format for APS ids (#2960) (ddf9257) # @permutive/javascript-sdk 20.57.0 (2025-12-01) ### Features * use cloud-lift-rust (#3043) (f70c16c) # @permutive/javascript-sdk 20.56.0 (2025-11-28) ### Features * **appnexus-adserver:** add disable setKeywords configuration (#3062) (56d8bc9) # @permutive/javascript-sdk 20.55.0 (2025-11-05) ### Features * **query-language:** support user-group cohorts ifp (#3024) (fd29b78) # @permutive/javascript-sdk 20.54.0 (2025-10-23) ### Features * **prebid\_monitoring:** bid adapters improvements (#3025) (4ff7205) ## @permutive/javascript-sdk 20.53.1 (2025-10-16) ### Bug Fixes * use dedicated MessageChannel for master - worker comms (#3021) (8e9b638) # @permutive/javascript-sdk 20.53.0 (2025-10-15) ### Features * **prebid\_monitoring:** includes `s2s_config` to prebid monitoring (#3016) (28ef4b7) ## @permutive/javascript-sdk 20.52.1 (2025-10-08) ### Bug Fixes * **monitoring:** video player metrics are incorrectly populated (#3006) (8dc77a7) # @permutive/javascript-sdk 20.52.0 (2025-10-02) ### Features * **prebid\_monitoring:** increase sampling from 1% to 5% (#2994) (8f79001) # @permutive/javascript-sdk 20.51.0 (2025-09-25) ### Features * **video-player-monitoring:** add additional metrics (#2991) (bb5683c) ## @permutive/javascript-sdk 20.50.1 (2025-09-23) ### Build System * **deps:** align babel versions (#2988) (432fecd) # @permutive/javascript-sdk 20.50.0 (2025-09-18) ### Features * **prebid\_monitoring:** include auctionDelay and jwp to rtd json string (#2984) (67576b6) # @permutive/javascript-sdk 20.49.0 (2025-09-12) ### Features * **metrics:** Prebid monitoring config metric - `sdk_prebid_monitoring_config_count_total` (#2971) (9ce1544) # @permutive/javascript-sdk 20.48.0 (2025-09-12) ### Features * **monitoring:** Video player metrics (#2974) (f318b53) # @permutive/javascript-sdk 20.47.0 (2025-08-19) ### Features * **cohorts:** add user-group cohort support (#2949) (d7a5e2d) ## @permutive/javascript-sdk 20.46.1 (2025-08-18) ### Bug Fixes * **adswizz:** use adswizz\_keyvalue integration key (#2951) (879fc08) # @permutive/javascript-sdk 20.46.0 (2025-08-14) ### Features * **AdsWizz:** create ad-server integration (#2942) (76cb01b) # @permutive/javascript-sdk 20.45.0 (2025-08-06) ### Features * **APS:** adds new integration with Amazon Publisher Services (#2938) (f00c5fc) # @permutive/javascript-sdk 20.44.0 (2025-08-01) ### Features * **logger:** add badges (#2937) (563c1d6) # @permutive/javascript-sdk 20.43.0 (2025-07-24) ### Features * **metrics:** inject geo `country` into MetricReporter (#2929) (8b8be5e) # @permutive/javascript-sdk 20.42.0 (2025-07-23) ### Features * **prebid\_monitoring:** send fine-grained ortb2 targeting metrics (#2920) (8911252) ## @permutive/javascript-sdk 20.41.1 (2025-07-09) ### Bug Fixes * **xandr-adserver:** improve mobile device click detection (#2905) (783acb3) # @permutive/javascript-sdk 20.41.0 (2025-07-07) ### Features * **curation:** Add curation everyone cohort (#2910) (907c197) # @permutive/javascript-sdk 20.40.0 (2025-06-25) ### Features * **appnexus:** support SPA use-case (#2895) (9ced311) ## @permutive/javascript-sdk 20.39.5 (2025-06-24) ### Bug Fixes * **contextual:** wire up cohort activations (#2904) (ab8122b) ## @permutive/javascript-sdk 20.39.4 (2025-06-20) ### Bug Fixes * **brightcove:** Update iframe src check for brightcove to also handle undefined (#2903) (fadcd92) ## @permutive/javascript-sdk 20.39.3 (2025-06-18) ### Reverts * Revert "fix(contextual): publish activated cohorts (#2900)" (c17e57e), closes #2900 ## @permutive/javascript-sdk 20.39.2 (2025-06-18) ### Bug Fixes * **contextual:** publish activated cohorts (#2900) (1158924) ## @permutive/javascript-sdk 20.39.1 (2025-06-18) ### Bug Fixes * **event-upload:** serialize state explicitly (#2901) (9924888) # @permutive/javascript-sdk 20.39.0 (2025-06-06) ### Features * **events-cache:** report age metrics (#2894) (e5376a1) ## @permutive/javascript-sdk 20.38.1 (2025-05-28) ### Bug Fixes * **xandr:** add gdpr params to identity request (#2887) (b383547) # @permutive/javascript-sdk 20.38.0 (2025-05-20) ### Features * **curation:** Activate segmented clean\_room cohorts (#2883) (50ff04d) ## @permutive/javascript-sdk 20.37.8 (2025-05-14) ### Bug Fixes * **contextual:** set max time to wait for tag call (#2881) (2039ff7) ## @permutive/javascript-sdk 20.37.7 (2025-05-01) ### Bug Fixes * **identity-manager:** add provider field to ID5 API call (#2875) (8d14831) ## @permutive/javascript-sdk 20.37.6 (2025-04-15) ### Bug Fixes * **tiktok-pixel:** update hashed email tag (#2796) (4537938) ## @permutive/javascript-sdk 20.37.5 (2025-04-11) ### Bug Fixes * **ctv:** enable for all organizations (#2872) (a4950d2) ## @permutive/javascript-sdk 20.37.4 (2025-04-11) ### Bug Fixes * **appnexus:** improve `AppNexusAdImpression` tracking (#2866) (a1ce544) ## @permutive/javascript-sdk 20.37.3 (2025-04-08) ### Performance Improvements * **memory:** create new task every iteration (#2871) (7e1e18b) ## @permutive/javascript-sdk 20.37.2 (2025-04-07) ### Performance Improvements * **tbt:** break up long running initialisation task (#2870) (f859a5c) ## @permutive/javascript-sdk 20.37.1 (2025-04-02) ### Performance Improvements * **pinterest:** filter request by tagId (#2867) (a46de51) # @permutive/javascript-sdk 20.37.0 (2025-03-20) ### Features * **tracking\_pixel:** Add support for tcf\_vendor\_id config (#2760) (f5232c4) ## @permutive/javascript-sdk 20.36.1 (2025-03-19) ### Bug Fixes * **context:** make available to custom scripts (#2832) (77e678c) # @permutive/javascript-sdk 20.36.0 (2025-03-18) ### Features * initialises new curation pipes (#2850) (212740a) # @permutive/javascript-sdk 20.35.0 (2025-03-17) ### Features * **tpd-usage:** only track usage for configured segments (#2849) (acf6d5f) ## @permutive/javascript-sdk 20.34.6 (2025-02-26) ### Bug Fixes * **identity-manager:** add identity based guard to liveramp provider (#2841) (fc3661d) ## @permutive/javascript-sdk 20.34.5 (2025-02-20) ### Code Refactoring * **processing-result:** sequence error result (ac0770e) ### Performance Improvements * **segmentation:** only process newly produced transition events (b903827) * **segmentation:** reword error on exceeding max iterations (90cdcf8) * **segmentation:** set maximum iterations for producing transition events (af91eb2) ## @permutive/javascript-sdk 20.34.4 (2025-02-20) ### Bug Fixes * **xandr:** activate classification cohorts (#2836) (d3a9471) ## @permutive/javascript-sdk 20.34.3 (2025-02-19) ### Performance Improvements * **events-cache:** block some events from persistence for specific workspaces (#2837) (fe1ff6e) ## @permutive/javascript-sdk 20.34.2 (2025-02-11) ### Performance Improvements * **lal:** refresh cached models (#2834) (c9dacc3) ## @permutive/javascript-sdk 20.34.1 (2025-02-07) ### Performance Improvements * **identity-manager:** improve caching across Pageviews (#2822) (f90fa7c) # @permutive/javascript-sdk 20.34.0 (2025-02-05) ### Features * **context:** allow values to override client properties (#2787) (0270cad) # @permutive/javascript-sdk 20.33.0 (2025-02-05) ### Features * **resource-timings:** track metric for asset (#2819) (c8a2d5a) # @permutive/javascript-sdk 20.32.0 (2025-01-22) ### Features * **cloudlift:** rename cloudlift endpoint (#2816) (f8824fb) ## @permutive/javascript-sdk 20.31.3 (2025-01-21) ### Performance Improvements * **build-service:** increase parallel scale to 5000 instances (#2815) (48bef2c) ## @permutive/javascript-sdk 20.31.2 (2025-01-20) ### Performance Improvements * **facebook pixel:** run fbq in separate macrotask to reduce tbt (#2666) (38496fe) ## @permutive/javascript-sdk 20.31.1 (2025-01-20) ### Bug Fixes * **doubleclick-pixel:** remove gdpr params for workspace (#2814) (0c06da2) # @permutive/javascript-sdk 20.31.0 (2025-01-17) ### Features * release identity manager (#2808) (e3bb82b) # @permutive/javascript-sdk 20.30.0 (2025-01-16) ### Features * integrate contextual data platform (#2788) (4937f77) ## @permutive/javascript-sdk 20.29.5 (2025-01-16) ### Bug Fixes * **identity-manager:** replace config values as strings (#2813) (c82e26c) ## @permutive/javascript-sdk 20.29.4 (2025-01-16) ### Bug Fixes * **prebid\_analytics:** normalize user\_id (#2811) (8d71b32) ## @permutive/javascript-sdk 20.29.3 (2025-01-13) ### Bug Fixes * **identity-manager:** liveramp rate limiting (#2805) (8e30f0d) ## @permutive/javascript-sdk 20.29.2 (2025-01-13) ### Bug Fixes * **build-service:** encode compressed asset as base64 (#2803) (fac8b9f) ## @permutive/javascript-sdk 20.29.1 (2025-01-09) ### Build System * **compression:** move to after asset verification (#2801) (b0936b3) # @permutive/javascript-sdk 20.29.0 (2025-01-09) ### Features * **prebid\_analytics:** prebidauctions\_events down sampling (#2795) (43a267d) ## @permutive/javascript-sdk 20.28.1 (2025-01-08) ### Bug Fixes * **appnexus\_adserver:** correctly re-implement `defineTag` (#2800) (8aef12c) # @permutive/javascript-sdk 20.28.0 (2025-01-07) ### Features * **prebid\_analytics:** save storage cost by opting out selected customers (#2797) (e17df7f) # @permutive/javascript-sdk 20.27.0 (2025-01-06) ### Features * **prebid\_analytics:** Separate from clean\_room (#2792) (a9b3b83) ## @permutive/javascript-sdk 20.26.2 (2024-12-18) ### Bug Fixes * **builds:** increase payload size limit (#2784) (400c480) ## @permutive/javascript-sdk 20.26.1 (2024-12-13) ### Bug Fixes * **transpilation:** produce compliant syntax for targets (#2785) (6caa1ce) # @permutive/javascript-sdk 20.26.0 (2024-12-11) ### Features * **build-service:** set invoker policy (#2782) (6cc5ec9) # @permutive/javascript-sdk 20.25.0 (2024-12-10) ### Features * enable cloudlift (#2755) (7b94d50) # @permutive/javascript-sdk 20.24.0 (2024-12-04) ### Features * **prebid:** Add advertiser domains to prebidbid event (#2776) (21ccc88) ## @permutive/javascript-sdk 20.23.4 (2024-12-02) ### Build System * **ctv:** modify allowed workspace list (#2779) (3e75751) ## @permutive/javascript-sdk 20.23.3 (2024-12-02) ### Bug Fixes * **facebook\_pixel:** call config value initialiser when firing fb pixel (#2774) (6f2f37f) ## @permutive/javascript-sdk 20.23.2 (2024-11-26) ### Bug Fixes * **facebook\_pixel:** fix config value not being initialised before constructor super call (#2772) (34b2658) ## @permutive/javascript-sdk 20.23.1 (2024-11-26) ### Build System * **build-service:** create http server (#2745) (aa21b0f), closes #2715 #2716 #2736 # @permutive/javascript-sdk 20.23.0 (2024-11-22) ### Features * **identity-manager:** allow geo restriction of id providers (#2762) (20ebbda) # @permutive/javascript-sdk 20.22.0 (2024-11-18) ### Features * **identity-manager:** liveramp id provider (#2757) (2406213) ## @permutive/javascript-sdk 20.21.1 (2024-11-18) ### Bug Fixes * **ampscript:** remove public version assignment (#2770) (b2b482f) # @permutive/javascript-sdk 20.21.0 (2024-11-14) ### Features * **facebook\_pixel\_v2:** Decide segment attach method using new core setup configuration value (#2769) (41571d4) ## @permutive/javascript-sdk 20.20.1 (2024-11-13) ### Bug Fixes * remove redundant Safari IndexedDB workaround (#2768) (2695071) # @permutive/javascript-sdk 20.20.0 (2024-11-13) ### Features * add sdkVersion to public API (#2767) (3225861) ## @permutive/javascript-sdk 20.19.2 (2024-11-05) ### Performance Improvements * **ql:** prevent unnecessary event replay (#2758) (5120b8f) ## @permutive/javascript-sdk 20.19.1 (2024-11-05) ### Bug Fixes * first page state partially lost in some scenarios (#2761) (ea47c69) # @permutive/javascript-sdk 20.19.0 (2024-10-30) ### Features * **identity manager:** add support for id5 (#2730) (acc5eac) # @permutive/javascript-sdk 20.18.0 (2024-10-30) ### Features * **clean\_room:** remove `pass_cohorts_to_prebid` flag (#2751) (8de4298) # @permutive/javascript-sdk 20.17.0 (2024-10-29) ### Build System * **sdks:** Enable streaming logs in grunt parallel build step (#2749) (ad8b4c7) ## @permutive/javascript-sdk 20.16.5 (2024-10-29) ### Build System * modify CTV build configuration (#2748) (00560fa) ## @permutive/javascript-sdk 20.16.4 (2024-10-25) ### Bug Fixes * **cloud lift:** ensure empty config adheres to type declaration (#2731) (e4592e8) ## @permutive/javascript-sdk 20.16.3 (2024-10-24) ### Build System * separate production and development steps (#2739) (6025044), closes #2715 #2716 #2736 ## @permutive/javascript-sdk 20.16.1 (2024-10-16) ### Bug Fixes * **secure signals:** removes suffixes from std audiences (#2734) (5afcabd) # 20.16.0 (2024-10-10) ### Features * **identity-manager:** implement basic id manager framework (#2721) (4429d6b) ## 20.15.2 (2024-10-10) ### Bug Fixes * replay degraded engagement queries (#2728) (b77ba69) ## 20.15.1 (2024-10-09) ### Bug Fixes * engagement queries degraded (#2724) (0bcc4f4) # 20.15.0 (2024-10-09) ### Features * **secure signals:** create addon (#2659 (7647c3f) ## 20.14.1 (2024-10-08) ### Bug Fixes * **cloud-lift:** add v1 version (#2723) (c611313) # 20.14.0 (2024-10-04) ### Built SDKs * **sdks:** filter org ctv sdks (#2722) (181a06d) # 20.13.0 (2024-10-02) ### Built SDKs * **sdks:** output specific ctv versions (tizen, lg webos) (#2714) (9c98989) # 20.12.0 (2024-10-01) ### Features * segmentation correctness metrics (#2717) (5a22353) ## 20.11.3 (2024-09-27) ### Performance Improvements * **QL:** use query.append where possible instead of state munger (#2709) (6de241b) ## 20.11.2 (2024-09-24) ### Performance Improvements * **QL:** compact historical QL state (#2706) (c0dc5ed) ## 20.11.1 (2024-09-24) ### Bug Fixes * do not report an error on bad query code (#2707) (34c7101) # 20.11.0 (2024-09-18) ### Features * **runtime:** use package implementation (#2682) (1d5d623) # 20.10.0 (2024-09-16) ### Code Refactoring * **metrics:** process on-worker metrics more eagerly (#2694) (830a599) ### Features * **cloud-lift:** include checksums in metadata (#2698) (dd430f0) ## 20.9.2 (2024-09-05) ### Bug Fixes * **tpd:** data not resolved when no identities are available (#2690) (5c56f75) ## 20.9.1 (2024-09-05) ### Bug Fixes * **ampscript:** local segmentation failing (#2692) (68219da) ### Code Refactoring * remove extension from import (b80c49b) # 20.9.0 (2024-08-21) ### Features * cloud lift (#2680) (967898d) ## 20.8.2 (2024-08-15) ### Reverts * revert cloud lift release temporarily (#2678) (258165d), closes #2676 #2665 ## 20.8.1 (2024-08-14) ### Performance Improvements * optimise 2pd/3pd processing (#2676) (c467c39) # 20.8.0 (2024-08-14) ### Features * cloud lift (#2665) (f314934), closes #2663 ## 20.7.2 (2024-08-07) ### Performance Improvements * **tpd:** re-enable optimisations (#2669) (bdd35b9) ## 20.7.1 (2024-08-06) ### Bug Fixes * **tpd:** tpd unreliably processed (#2668) (d11d7c2) # 20.7.0 (2024-07-31) ### Features * clean\_room v4 default (#2661) (a397665) ## 20.6.1 (2024-07-26) ### Bug Fixes * **google-rtd:** add gdpr to cookie matching pixel (#2655) (d6b742) # 20.6.0 (2024-07-26) ### Features * **clean-room:** expose advertiser programmatic cohorts (#2645) (7ed5200) ## 20.5.2 (2024-07-19) ### Bug Fixes * **facebook\_pixel:** add new custom event (#2649) (c568e7b) ## 20.5.1 (2024-07-17) ### Bug Fixes * **ctv:** allow event property client as input to addon (#2641) (0db4500) # 20.5.0 (2024-07-15) ### Features * **pubmatic:** set gdpr parameters from tcf (#2642) (16cb950) ## 20.4.6 (2024-07-10) ### Bug Fixes * use setIntervalSdk to ensure compute is measure (#2635) (d816f3e) ### Performance Improvements * load watson data earlier (#2634) (8ab2b5b) ## 20.4.5 (2024-07-09) ### Performance Improvements * **worker:** run most worker features immediately (#2631) (38b0288) ## 20.4.4 (2024-07-04) ### Performance Improvements * **worker:** run worker functions earlier (#2630) (1a2e608) ## 20.4.3 (2024-07-03) ### Code Refactoring * **clean room:** drops unused either wrapper (#2615) (8dffe19) ### Performance Improvements * **appnexus pixel:** optimise init with large no cohorts (#2629) (af92612) ## 20.4.2 (2024-07-01) ### Bug Fixes * **dfp:** not possible to drop out of cloud cohorts during pv (#2623) (1f4ddc9) ### Performance Improvements * **clm:** run segmentation immediately (#2624) (e95262b) ## 20.4.1 (2024-06-26) ### Performance Improvements * **state-sync:** defer crdt computation to not block worker context (#2617) (a457a5a) # 20.4.0 (2024-06-26) ### Features * add additional critical path metrics (#2620) (d78dbeb) ## 20.3.2 (2024-06-26) ### Bug Fixes * **metrics:** event upload success/fail metrics inverted (#2618) (41a337f) ## 20.3.1 (2024-06-26) ### Performance Improvements * **tpd:** eliminate some redundant tpd re-processing (#2613) (2555006) # 20.3.0 (2024-06-25) ### Features * **clean-room:** frequency control using segmentation v4 (#2607) (b04c756) ## 20.2.2 (2024-06-25) ### Performance Improvements * **metrics:** add timings to critical path (#2593) (52f91f6) ## 20.2.1 (2024-06-21) ### Bug Fixes * **event-upload:** `client` properties can be overridden (#2609) (fa505f8) # 20.2.0 (2024-06-20) ### Features * **clean-room:** set v4 segmentation to default (#2606) (cd9e96c) ## 20.1.1 (2024-06-18) ### Bug Fixes * **tcf:** port to using `addEventListener` from `getTCData` (#2598) (f350f9e) # 20.1.0 (2024-06-11) ### Code Refactoring * **ref:** replace `fold` with `scan` (#2587) (2fddebd) ### Features * **metrics:** synchronise time between main and worker contexts (#2591) (138c63a) ## 20.0.3 (2024-06-07) ### Performance Improvements * do not persist AdRequest events in events cache (#2588) (0e99e1c) ## 20.0.2 (2024-06-07) ### Performance Improvements * **lal:** persist lal separately from core state (#2586) (870b36c) ## 20.0.1 (2024-06-06) ### Performance Improvements * **timings:** record and surface timings and traces (#2567) (808c04a) ## 20.0.0 (2024-06-03) ### Performance Improvements * move majority of SDK compute to a background thread (#2296) (810f7fb), closes #2415 ## 19.120.1 (2024-05-29) ### Bug Fixes * ensure privacy sandbox topics compute is measured (9fdfa97) * **idb:** recreate object stores during upgrade transaction for safari (5036ea8) # 19.120.0 (2024-05-21) ### Features * **api metrics:** use native number and boolean metric labels (22ee3fd) ### Performance Improvements * **cohort metrics:** optimise implementation (#2549) (e2a18d3) # 19.119.0 (2024-05-20) ### Features * **metrics:** always track replay count forcing 0 when no events on device (#2546) (f9d99f4) # 19.118.0 (2024-05-20) ### Features * add cohort membership metrics (#2542) (8fc6e8e) * **queries:** add metric for occurrences of queries requiring replay (#2541) (4a7b8b9) # 19.117.0 (2024-05-16) ### Features * **reaction:** disable event upload for specific organisation (#2536) (3b8fabf) ## 19.116.1 (2024-05-15) ### Code Refactoring * simplify metrics reporting (917e81c) ### Performance Improvements * **metrics:** aggregate counter metrics client-side (8ee0260) * **metrics:** stop sending requests if the api is unhealthy (e2e4929) # 19.116.0 (2024-04-30) ### Features * **provider:** enable ip provider (#2496) (1396e30) # 19.115.0 (2024-04-29) ### Features * **ip identity provider:** Add IP Address identity provider (#2480) (81c3bca) ## 19.114.2 (2024-04-26) ### Bug Fixes * **privacy sandbox topics:** event upload failing prior to topic retrieval (#2493) (6134080) ## 19.114.1 (2024-04-24) ### Bug Fixes * **trade desk:** fix id sync for non-gdpr users (#2486) (3e50913) # 19.114.0 (2024-04-23) ### Features * **clean-room:** default to api v3 for advertiser segmentation (#2482) (a78a1a6) # 19.113.0 (2024-04-19) ### Features * **worker:** report errors and metrics on health of web worker (#2447) (c9be1a7) # 19.112.0 (2024-04-17) ### Features * **privacy-sandbox-topics:** rename topics event field to avoid collisions (#2462) (4e86426) ## 19.111.1 (2024-04-16) ### Bug Fixes * **privacy sandbox topics:** enrichment broken on second+ pv (d7086df) # 19.111.0 (2024-04-12) ### Features * **privacy-sandbox-topics:** add topics to be tracked in events (#2456) (df908a1) # 19.110.0 (2024-04-11) ### Features * **clean-room:** enable api v3 for advertiser segmentation (#2435) (daf8da8), closes #2440 # 19.109.0 (2024-04-05) ### Features * **programmatic:** suffixed segment support (#2442) (f33942a) # 19.108.0 (2024-04-04) ### Features * **programmatic:** don't wait for all addons to load (#2438) (ee56899) ## 19.107.1 (2024-04-03) ### Bug Fixes * **ssp:** affinity cohorts not being applied (#2433) (ada3460) # 19.107.0 (2024-03-28) ### Features * **programmatic:** custom cohort mapping + affinity cohorts via config flag (#2426) (d9d53e3) ## 19.106.1 (2024-03-26) ### Reverts * Reverts "feat(programmatic): add affinity cohorts and custom cohort mapping (fbf774f)" # 19.106.0 (2024-03-26) ### Features * **programmatic:** add affinity cohorts and custom cohort mapping (fbf774f) ## 19.105.3 (2024-03-20) ### Performance Improvements * **audience matching:** eliminate unnecessary usage reporting (db39e83) ## 19.105.2 (2024-03-20) ### Performance Improvements * **audience matching:** do not report usage for 'pug' provider (bc5ef95) ## 19.105.1 (2024-02-13) ### Bug Fixes * **globalThis:** remove usage for compatibility with older environments (#2396) (de5089e) # 19.105.0 (2024-02-12) ### Features * **contextual:** support tag v2 by expanding addon (#2357) (d28714a) # 19.104.0 (2024-01-23) ### Features * **tiktok:** Add TikTok pixel addon (#2358) (82b26f1) ## 19.103.4 (2024-01-16) ### Bug Fixes * **Reaction:** on disabled event upload, call event handler locally for processing (#2372) (7bf31f1) ## 19.103.3 (2024-01-16) ### Bug Fixes * **api:** enable CTV SDKs to use https by using host with non-expired certificate (#2265) (ea8953b) ## 19.103.2 (2024-01-12) ### Performance Improvements * **dfp:** improve `SlotClicked` tracking reliability (#2370) (d7946c5) ## 19.103.1 (2024-01-08) ### Bug Fixes * **dfp:** duplicate SlotClicked events (#2369) (7b7d676) # 19.103.0 (2024-01-05) ### Features * **analytics:** wait for cohorts before uploading events (#2356) ## 19.102.1 (2023-12-11) ### Bug Fixes * **contextual:** parse input without throwing error (fee4c6d) # 19.102.0 (2023-12-05) ### Features * **contextual:** create addon and apply cohorts to events (#2331) (12e295b) # 19.101.0 (2023-11-15) ### Features * **query-language:** support larger queries via update qlr to v10.0.2 (#2311) (16572d6) ## 19.100.3 (2023-11-10) ### Bug Fixes * **appnexus-adserver:** remove customer specific check (#2304) (e0a1955) ## 19.100.2 (2023-11-10) ### Performance Improvements * **configuration:** dedupe inlined config (#2297) (83aada6) ## 19.100.1 (2023-11-10) ### Bug Fixes * **identities:** let insecure aliases (i.e `email_sha256`) trigger update by filtering writes only (#2291) (c0f6f59) # 19.100.0 (2023-11-09) ### Features * **prebid-identifiers:** track eid source for analytic purposes # 19.99.0 (2023-11-08) ### Features * **query-language:** interpret front compression via update qlr to v9.0.0 (#2282) (f81d368) ## 19.98.2 (2023-11-06) ### Bug Fixes * do not fetch advertiser cohorts until SDK is realtime (#2287) (06102c6) ## 19.98.1 (2023-10-27) ### Bug Fixes * **event-persistence:** prevent `PrebidAuctions` analytic event from being persisted (#2273) (8204b24) # 19.98.0 (2023-10-16) ### Features * **ql:** Bump ql-runtime to v8.0.2 - adding binary string equality (#2242) (54a9c76) # Chrome Extension Source: https://docs.permutive.com/sdks/web/javascript-sdk/troubleshooting/chrome-extension Validate your Permutive deployment by inspecting data collection, schema errors, cohort membership, and ad request targeting ## Overview The Permutive Chrome Extension allows publishers to validate their Permutive deployment directly in the browser. It provides real-time visibility into what data is being collected, whether there are any schema errors, which cohorts a user belongs to, and whether ad requests are being targeted correctly with Permutive cohorts. The extension is a diagnostic and debugging tool designed for publishers and their technical teams to verify that their Permutive SDK integration is functioning correctly across event tracking, cohort evaluation, ad targeting, and Prebid configuration. ## Why Use the Chrome Extension? **Validate your deployment in real time** — Instantly verify that Permutive is collecting data correctly on any page with the **web JavaScript SDK** deployed. See every event request, its payload, and whether it was accepted or rejected. **Debug schema and tracking errors** — When events are rejected, the extension shows exactly why, including detailed error messages for schema rejections. **Verify ad targeting** — Confirm that Google Ad Manager ad units are being targeted with Permutive cohorts. See at a glance whether each ad request used real-time cohorts, cached cohorts from a previous page, or was not targeted at all. **Inspect Prebid configuration** — Check that Prebid.js is correctly configured for header bidding with Permutive cohorts, including module installation status, bidder configuration, and which cohort types are being passed in auctions. ## Concepts ### Definitions * **Organization ID**: Your unique organization identifier. You can find this ID by clicking your name in the top right corner and click Workspace Settings from the drop-down menu. Required to configure the extension. * **Event Request**: A data payload sent from the Permutive SDK to Permutive's servers when a user action is tracked (e.g., Pageview, VideoView, or custom events). * **Schema Rejection**: An event that was rejected because its properties did not match the expected schema definition. The extension displays detailed error messages explaining the mismatch. See [Creating & Updating Event Schema](/guides/connectivity/events/create-update-event-schema) for how to define and modify schemas. * **Real-Time Targeting**: Ad units targeted with cohorts computed by the SDK on the current page before the ad request was sent. Indicated by a star icon in the Ads view. * **Cached Targeting**: Ad units targeted with cohort data from local storage that was computed on a previous page, sent before the SDK was initialized on the current page. Indicated by a check icon in the Ads view. * **Identity Request**: An event that passes user aliases (identifiers) to Permutive for identity resolution. ## Workflows ### Installation and Setup After installing the Permutive Chrome Extension from the Chrome Web Store, you configure it with your Organization ID. This links the extension to your Permutive workspace and enables the diagnostic features. Chrome Extension config module.

### Opening the Extension When the web JavaScript SDK that is associated with your organization is detected, the Permutive extension icon should automatically turn black and the extension should pop open on the right. You can minimize it by clicking on the black Permutive icon. Chrome Extension detecting the web JavaScript SDK and opening.

Chrome Extension detecting the web JavaScript SDK and opening.

If the web JavaScript SDK is not detected, the Permutive icon should be grey. Chrome Extension not detecting the web JavaScript SDK and staying closed.

Chrome Extension not detecting the web JavaScript SDK and staying closed.

### Inspecting Event & Identity Requests The Requests view shows all Permutive event and identity requests on the current and previous pageview. Each event request displays a status indicator: a check for successful requests or an "x" for rejected requests. Clicking on an event name reveals its full payload and properties. For rejected events, the extension shows the specific reason for rejection, such as an unknown event type or a schema validation error. The example below shows an event being rejected because it was not defined in the schema. Chrome Extension showing an accepted and rejected event.

Chrome Extension showing an accepted and rejected event.

The example below shows an event being rejected because an extra property was added that was not defined in the schema. Chrome Extension showing a rejected event because an extra property was added to the payload.

Chrome Extension showing a rejected event because an extra property was added to the payload.

For identity requests, you can click the request to view further details: the identities collected, priority of each, and the actual identity value. You may notice that not every page-load will have an identity request. For SDK performance reasons, identity requests only fire when a brand new identifier is collected (e.g. an identifier type that hasn't been attributed to a user before or the value of an identifier has been updated). Chrome Extension showing an identity request.

Chrome Extension showing an identity request.

Events are generally rejected for one of two reasons: the event type is unknown, or the event properties fail schema validation. For schema rejections, the extension shows detailed error messages when you inspect the event properties. To fix schema issues, see [Creating & Updating Event Schema](/guides/connectivity/events/create-update-event-schema). ### Viewing Cohort Membership The Cohorts view displays all cohorts that the current user falls into. Cohort codes are shown, which can be looked up in the Permutive Dashboard to find the corresponding cohort names. Chrome Extension showing searching for a cohort code within the cohorts tab.

Chrome Extension showing searching for a cohort code within the cohorts tab.

### Verifying Ad Targeting The Ads view provides an overview of all Google Ad Manager ad requests on the current page and whether they were targeted with Permutive cohorts. Each ad request shows a status indicator: * **Star** — Targeted with real-time cohorts computed on the current page before the ad request was sent. * **Check** — Targeted with cached cohorts from local storage, sent before the SDK was initialized on the current page. * **Circled exclamation point** — Not targeted with Permutive cohorts. Clicking on an individual ad request reveals more details, including targeting keys. The "i" info icon next to the cohorts parameter shows where Permutive cohorts appear in the ad request. When cohorts listed under the `cust_params.permutive` property have the `rts` flag appended, it means the ad was targeted with real-time cohorts. The example below shows an ad having a star as the status indicator. This is because the `rts` flag was included in the cohort list, marking them as real-time cohorts. Chrome Extension showing an event being targeted with Permutive cohorts in real-time.

Chrome Extension showing an event being targeted with Permutive cohorts in real-time.

### Checking Prebid Configuration The Prebid view allows you to verify your Prebid.js header bidding integration with Permutive. It shows: * Whether the default required Prebid modules are installed correctly * Defined bidders and their configuration * Which cohort types (custom and standard) are being passed in auctions Status indicators help diagnose configuration issues: * All red "x" marks under "Cohorts Passed In Auctions" indicate a possible incorrect installation. * Red exclamation marks under "Prebid Configuration Checks" combined with green checks under "Cohorts Passed in Auctions" indicate a custom configuration. ### Reviewing Consent Framework The extension also shows consent framework behavior on the current page, indicating whether a user has given consent and whether consent is required. How consent is setup and managed is up to your legal and developer teams. The example below shows a deployment where consent is not required and the SDK does not wait on consent to be given. Chrome Extension showing a deployment where consent is not required and the SDK does not wait on consent to be given.

Chrome Extension showing a deployment where consent is not required and the SDK does not wait on consent to be given.

The example below shows a deployment where consent is required and the SDK does wait for consent to be given (and consent has been given). Chrome Extension showing a deployment where consent is required and the SDK waits on consent to be given (and it is given).

Chrome Extension showing a deployment where consent is required and the SDK waits on consent to be given (and it is given).

## Troubleshooting The extension icon turns black when it detects Permutive on the current page. If the icon remains grey: **Solution:** * Verify that the Permutive SDK is deployed on the page by checking the browser developer console for Permutive-related scripts * Ensure you have entered the correct Organization ID in the extension options (right-click the extension icon > Manage Extension) * Try refreshing the page after configuring the extension # Common Errors Source: https://docs.permutive.com/sdks/web/javascript-sdk/troubleshooting/common-errors Troubleshoot common issues with the Permutive JavaScript SDK This guide covers common issues and their solutions when integrating the Permutive JavaScript SDK. The [Permutive Chrome Extension](/sdks/web/javascript-sdk/troubleshooting/chrome-extension) provides a visual way to inspect event requests, schema errors, cohort membership, and ad targeting without using the browser developer console. ## Installation Issues **Symptoms:** * `window.permutive` is undefined * No console messages with debug mode * Network tab shows 404 for live.js **Solutions:** 1. **Verify script URL** ```html theme={"dark"} ``` 2. **Check for Content Security Policy (CSP) issues** ``` Content-Security-Policy: script-src 'self' https://*.permutive.app; connect-src 'self' https://*.permutive.com https://*.permutive.app; ``` 3. **Ensure loader script runs first** The inline loader script must execute before the SDK script loads. 4. **Check for JavaScript errors** Earlier errors may prevent subsequent scripts from running. **Symptoms:** * Syntax errors in console * `permutive is not defined` errors **Solutions:** 1. **Verify loader script is complete** Ensure the entire loader script is copied correctly: ```javascript theme={"dark"} !function(e,o,n,i){if(!e){e=e||{},window.permutive=e,e.q=[];var t=function(){return([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,function(e){return(e^(window.crypto||window.msCrypto).getRandomValues(new Uint8Array(1))[0]&15>>e/4).toString(16)})};e.config=i||{},e.config.apiKey=o,e.config.workspaceId=n,e.config.environment=e.config.environment||"production",(window.crypto||window.msCrypto)&&(e.config.viewId=t());for(var g=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user","consent"],r=0;r","",{}); ``` 2. **Check for quote issues** Template engines may escape quotes incorrectly. 3. **Verify API key and workspace ID** Ensure credentials don't contain special characters that need escaping. **Symptoms:** * Console error: "Refused to load the script..." * Console error: "Blocked by Content Security Policy" **Solution:** Add Permutive domains to your Content Security Policy: ``` Content-Security-Policy: script-src 'self' https://*.permutive.app; connect-src 'self' https://*.permutive.com https://*.permutive.app; img-src 'self' https://*.permutive.com; ``` **Symptoms:** * SDK loads on some browsers but not others * Network requests blocked **Solutions:** 1. Most ad blockers do not block Permutive as it's a first-party tool 2. If blocked, users will still see the site but without personalization 3. Test with ad blockers disabled to confirm this is the cause ## Tracking Issues **Symptoms:** * `track()` called successfully * Debug mode shows "Event accepted" * Nothing in Permutive dashboard **Solutions:** 1. **Wait for processing** Events may take a few minutes to appear in the dashboard. 2. **Check date/time filters** Ensure dashboard filters include the current time period. 3. **Verify workspace** Confirm you're viewing the correct workspace in the dashboard. 4. **Check consent status** If `consentRequired: true`, ensure consent was granted: ```javascript theme={"dark"} permutive.consent({ opt_in: true, token: 'abc' }); ``` **Symptoms:** * No Pageview events * Other events work but not pageviews **Solutions:** 1. **Verify web addon is called** ```javascript theme={"dark"} permutive.addon('web', { page: { type: 'article' } }); ``` 2. **Check consent timing** If using consent, call `consent()` before `addon('web')`: ```javascript theme={"dark"} permutive.consent({ opt_in: true, token: 'abc' }); permutive.addon('web', { page: { type: 'article' } }); ``` 3. **Check for duplicate calls** Ensure `addon('web')` isn't called multiple times. **Symptoms:** * `consentRequired: true` configured * Events called but not tracked * No errors in console **Cause:** Events called before `consent({ opt_in: true })` are discarded (not queued). **Solution:** Always call `consent()` before tracking: ```javascript theme={"dark"} // 1. Grant consent first permutive.consent({ opt_in: true, token: 'abc' }); // 2. Then initialize tracking permutive.addon('web', { page: { type: 'article' } }); ``` **Symptoms:** * First pageview tracks * Subsequent route changes don't track **Solution:** Call `permutive.addon('web', {...})` on each route change: ```javascript theme={"dark"} // On route change router.onRouteChange(function() { permutive.addon('web', { page: getPageProps() }); }); ``` **Symptoms:** * Different user ID on each visit * User history not persisting **Causes:** * Cookies being blocked or cleared * Private browsing mode * Cookie domain mismatch **Solutions:** 1. **Check cookie exists** Look for `permutive-id` in Application > Cookies 2. **Verify cookie domain** Ensure domain matches your configuration: ```javascript theme={"dark"} { cookieDomain: '.example.com' } ``` 3. **Check browser settings** Some browsers aggressively clear first-party cookies. ## Targeting Issues **Symptoms:** * `permutive.segments()` returns `[]` * localStorage keys empty **Solutions:** 1. **Wait for realtime data** ```javascript theme={"dark"} permutive.ready(function() { permutive.segments(function(segs) { console.log(segs); // Now populated }); }, 'realtime'); ``` 2. **Verify cohorts exist** Check that cohorts are configured in dashboard. 3. **Confirm user qualifies** User must meet cohort criteria to be included. 4. **Check consent** Cohorts require consent to be tracked and calculated. 5. **Allow processing time** New cohort membership may take a few seconds. **Symptoms:** * Segments exist in localStorage * Targeting set on GPT * Line items not matching **Solutions:** 1. **Verify key name** Ensure GAM key is exactly `permutive` (case-sensitive). 2. **Check value format** Values should be strings, not numbers. 3. **Verify targeting in Google Publisher Console** Add `?googfc` to URL and check targeting values. 4. **Confirm line item targeting** Double-check line item uses correct key-value targeting. **Symptoms:** * RTD module configured * Bid requests missing Permutive data **Solutions:** 1. **Verify RTD module included** Check Prebid build includes `permutiveRtdProvider`. 2. **Check configuration** ```javascript theme={"dark"} pbjs.setConfig({ realTimeData: { auctionDelay: 200, dataProviders: [{ name: 'permutive', waitForIt: true // Critical! }] } }); ``` 3. **Add TCF exception if needed** ```javascript theme={"dark"} vendorExceptions: ['permutive'] ``` 4. **Check localStorage** Verify segment data exists in `_pdfps`, `_papns`, etc. **Symptoms:** * User should qualify for new cohorts * Segments remain unchanged **Solutions:** 1. **Verify events are tracking** Check dashboard for incoming events. 2. **Check cohort rules** Ensure user behavior matches cohort criteria. 3. **Allow processing time** Cohort updates may take a few seconds to minutes. 4. **Refresh page** Page reload triggers re-evaluation. 5. **Use triggers for real-time** ```javascript theme={"dark"} permutive.trigger(12345, 'segment', function(inCohort) { console.log('Cohort status:', inCohort); }); ``` ## Console Errors **Cause:** SDK not loaded when method called. **Solutions:** 1. Ensure loader script runs before any `permutive.*` calls 2. Check for script loading errors 3. Verify script placement in `` **Causes:** * Network connectivity issues * API endpoint unreachable * Request blocked **Solutions:** 1. Check network connectivity 2. Verify no proxy/firewall blocking 3. Check CSP configuration 4. Enable debug mode for details **Cause:** Missing or incorrect API key/workspace ID. **Solutions:** 1. Verify API key from dashboard 2. Verify workspace ID from dashboard 3. Check for extra whitespace or newlines 4. Ensure credentials match environment (production vs staging) ## Debug Mode Enable debug mode to diagnose issues: ``` https://yoursite.com/page?__permutive.loggingEnabled=true ``` Debug output includes: * SDK initialization status * Event tracking confirmations * Segment calculations * API request/response details * Error messages ## Getting More Help If you can't resolve the issue: 1. **Gather diagnostic information:** * Debug mode console output * Network tab screenshots * localStorage contents * Browser and version 2. **Contact support:** * Customer Success Manager * [Technical Services](mailto:technical-services@permutive.com) ## Related Documentation Visual deployment validation tool Installation options Verify integration Consent handling Understanding cohorts

AdsWizz

Google Ad Manager

Microsoft Monetize (Ad Server)

Equativ

FreeWheel

Nativo

AdsWizz

Equativ

FreeWheel

Google Ad Manager

Nativo

Microsoft Monetize (Ad Server)

Amazon Publisher Services (APS)

Prebid

Amazon Publisher Services

Prebid

Adform

DV360

The Trade Desk

Adform

StackAdapt

DV360

StackAdapt

The Trade Desk

Microsoft Monetize (SSP)

OpenX

PubMatic

Magnite

Index Exchange

Index Exchange

Magnite

OpenX

PubMatic

Microsoft Monetize (SSP)

IBM Watson

Silverbullet 4D

OS Data Solutions

TextRazor

IBM Watson

OS Data Solutions

Silverbullet 4D

TextRazor

AWS S3

Google BigQuery

Snowflake

BigQuery

AWS S3

Google Cloud Storage

Google Cloud Storage

Snowflake

UID2

ID5

RampID

ID5

LiveRamp RampID

UID2

mParticle

mParticle

Adestra

Salesforce Marketing Cloud

Adestra

Sailthru

Sailthru

Salesforce Marketing Cloud

Google Ad Manager

Prebid

The Trade Desk

DV360

Magnite

Snowflake

Facebook

Instagram

X (Twitter)

LinkedIn

Pinterest

TikTok

YouTube

Facebook

Instagram

LinkedIn