Running Experiments — Activate, Get Variation, Track Goal

Running Experiments — Activate, Get Variation, Track Goal

Activate Experiment
Call activateExperiment to assign a user to an experiment and record the assignment. The SDK checks targeting conditions, runs the user through bucketing logic, and returns the variation name via a completion handler.
Method  
  1. swift
  2. import PageSenseFramework
  3. pageSenseClient.activateExperiment(
  4.     experimentName: String,
  5.     userId: String,
  6.     userAttributes: [String: String]
  7. ) { variationName in
  8.     if variationName != nil {
  9.         print("Variation assigned successfully")
  10.     } else {
  11.         print("User not qualified or experiment inactive")
  12.     }
  13. }
Parameters  

Parameter

Type

Description

experimentName

String

The experiment to activate.

userId

String

A unique identifier for the user.

userAttributes

Dictionary

Key-value pairs used for audience targeting and segmentation.


Return Value  
  • Variation name — if the user qualifies and is bucketed into the experiment.
  • nil — if the user doesn't meet targeting criteria or falls outside traffic allocation.
Usage Example  
  1. swift
  2. import PageSenseFramework
  3. var currentVariationName: String?
  4. var userAttributes: [String: String] = [:]
  5. userAttributes["DeviceType"] = "Phone"
  6. userAttributes["OS"] = "iOS"
  7. userAttributes["OSVersion"] = "17.0"
  8. userAttributes["DeviceModel"] = "iPhone 15 Pro"
  9. pageSenseClient.activateExperiment(
  10.     experimentName: "experimentName",
  11.     userId: userId,
  12.     userAttributes: userAttributes
  13. ) { variationName in
  14.     guard let self = self else { return }
  15.     self.currentVariationName = variationName
  16. }
  17. func applyVariation() {
  18.     if currentVariationName == "original" {
  19.         // Handle Original
  20.     } else if currentVariationName == "Variation 1" {
  21.         // Handle Variation 1
  22.     } else if currentVariationName == "Variation 2" {
  23.         // Handle Variation 2
  24.     } else {
  25.         // User not qualified or variation is nil
  26.     }
  27. }
How the SDK evaluates a user  

Step 1 — Audience Targeting
The SDK checks the userAttributes dictionary against the experiment's targeting conditions. If the user doesn't qualify, nil is returned immediately — no bucketing occurs.

Step 2 — MurmurHash Bucketing
The SDK hashes the combination of User ID + Experiment Key using MurmurHash. This produces a consistent number between 0 and 9999.
Because the Experiment Key is part of the hash input, the same user gets a different hash value for each experiment — keeping variation assignments independent across experiments.

Step 3 — Variation Mapping
Each variation owns a slice of the 0–9999 range. The SDK checks where the user's hash value lands.
Variation
Hash Range
Original
0 – 2000
Variation 1
2001 – 4000
Variation 2
4001 – 6000
If the hash lands within a range, that variation is assigned. If it falls outside all ranges, nil is returned.

Step 4 — Tracking
Once a variation is assigned, the SDK fires tracking data to PageSense asynchronously — it doesn't block the main thread or impact UI performance.

Get Variation Name
getVariationName works exactly like activateExperiment — same targeting check, same MurmurHash bucketing — but it doesn't send any tracking data to PageSense. Use it when you need to know a user's variation without logging an impression.

Method  
  1. swift
  2. import PageSenseFramework

  4. pageSenseClient.getVariationName(
  5.     experimentName: String,
  6.     userId: String,
  7.     userAttributes: [String: String]
  8. ) { variationName in
  9.     if variationName != nil {
  10.         print("Variation fetched successfully")
  11.     } else {
  12.         print("User not qualified or experiment inactive")
  13.     }
  14. }
Parameters  

Parameter
Type
Description
experimentName
String
The experiment to check.
userId
String
A unique identifier for the user.
userAttributes
Dictionary
Key-value pairs used for audience targeting and segmentation.

Return Value  
  • Variation name — if the user qualifies for the experiment.
  • nil — if the user doesn't meet targeting conditions or falls outside traffic allocation.
Usage Example  

  1. swift
  2. import PageSenseFramework
  3. var currentVariationName: String?
  4. var userAttributes: [String: String] = [:]
  5. userAttributes["DeviceType"] = "Phone"
  6. userAttributes["OS"] = "iOS"
  7. userAttributes["OSVersion"] = "17.0"
  8. userAttributes["DeviceModel"] = "iPhone 15 Pro"
  9. pageSenseClient.getVariationName(
  10.     experimentName: "experimentName",
  11.     userId: userId,
  12.     userAttributes: userAttributes
  13. ) { variationName in
  14.     guard let self = self else { return }
  15.     self.currentVariationName = variationName
  16. }
  17. func applyVariation() {
  18.     if currentVariationName == "original" {
  19.         // Handle Original
  20.     } else if currentVariationName == "Variation 1" {
  21.         // Handle Variation 1
  22.     } else if currentVariationName == "Variation 2" {
  23.         // Handle Variation 2
  24.     } else {
  25.         // User not qualified or variation is nil
  26.     }
  27. }
The evaluation runs the same steps as activateExperiment — audience targeting → MurmurHash bucketing → variation mapping. The only difference: no tracking event is sent to PageSense.

Variation
Hash Range
Original
0 – 2000
Variation 1
2001 – 4000
Variation 2
4001 – 6000

Track Goal
Call trackGoal when a user completes an action you've defined as a goal in PageSense — a purchase, a form submission, a button tap. The SDK checks whether the user qualifies for the experiment first. If they don't, the call is silently dropped — nothing breaks, nothing is recorded.

Method  
  1. swift
  2. pageSenseClient.trackGoal(
  3.     experimentName: String,
  4.     userId: String,
  5.     goalName: String,
  6.     userAttributes: [String: String]
  7. )
Parameter

Parameter

Type

Description

experimentName

String

The experiment this goal belongs to.

userId

String

A unique identifier for the user.

goalName

String

The name of the goal to track.

userAttributes

Dictionary

Key-value pairs used for audience targeting and segmentation.


When is a conversion actually recorded?  
Two conditions must both be true:
  • The user qualifies for the experiment (targeting rules + traffic allocation).
  • The user completes the goal action.
Goals must be configured inside your experiment in PageSense before this API can record anything. If the user doesn't qualify, the call is ignored.

Usage Example  
  1. swift
  2. var userAttributes: [String: String] = [:]
  3. userAttributes["DeviceType"] = "Phone"
  4. userAttributes["OS"] = "iOS"
  5. userAttributes["OSVersion"] = "17.0"
  6. userAttributes["DeviceModel"] = "iPhone 15 Pro"
  7. pageSenseClient.trackGoal(
  8.     experimentName: "experimentName",
  9.     userId: userId,
  10.     goalName: "goalName",
  11.     userAttributes: userAttributes
  12. )
How the SDK processes it 
 
Step 1 — Audience Targeting
userAttributes are checked against the experiment's targeting rules. If the user doesn't qualify, the call is dropped silently.

Step 2 — User Qualification via Bucketing
The SDK applies MurmurHash to the User ID + Experiment Key combination. If the resulting hash falls within a variation's range, the user qualifies for the experiment.

Step 3 — Conversion Recorded
If the user qualifies, the SDK sends the goal conversion data to PageSense asynchronously — no main thread blocking, no UI impact. The data feeds into experiment analytics, conversion reports, and variation performance evaluation.
 



We’ve designed this documentation to guide you every step of the way. If you need further assistance or have any questions, don’t hesitate to contact us at support@zohopagesense.com - we’re always here to help!