Kroach/oasis 1397 forced variation (#159)

kellyroach-optimizely · web-flow · commit 92f3a79ee9c5 · 2017-07-24T12:04:49.000-07:00
* Add OptimizelyBucketId * Add stub setForcedVariation:userId:variationKey * Add getForcedVariation and setForcedVariation to OPTLYProjectConfig.m+.h * OPTLYDecisionService ---- check for forced variation ---- * Add setForcedVariation to Optimizely.m * Add testSetForcedVariationExperimentNotRunning * Add testGetVariationWithWhitelistedVariationOverriddenBySetForcedVariation * Add testGetVariationWithInvalidAudienceOverriddenBySetForcedVariation * Objective-C Implmentation of "Forced Bucketing" and "Bucketing ID" Design Docs Summary: OASIS-1397 Reference implementation for Forced variations and bucketing keys in one SDK Add OptimizelyBucketId Add stub setForcedVariation:userId:variationKey Add getForcedVariation and setForcedVariation to OPTLYProjectConfig.m+.h OPTLYDecisionService ---- check for forced variation ---- Add setForcedVariation to Optimizely.m Add testSetForcedVariationExperimentNotRunning Add testGetVariationWithWhitelistedVariationOverriddenBySetForcedVariation Add testGetVariationWithInvalidAudienceOverriddenBySetForcedVariation Add a couple more test asserts Test Plan: Added 3 tests which pass to OPTLYDecisionServiceTest.m Reviewers: alda JIRA Issues: OASIS-1397 Differential Revision: https://phabricator.optimizely.com/D16606 * Add fourth test and remove yellow caution when nil is passed as variationKey to setForcedVariation:userId:variationKey: * Add fifth test * Add sixth test * Improved error handling and logging in setForcedVariation:userId:variationKey: * Change setForcedVariation to return a BOOL, agreeing with revised spec. * preferredVariationMap should cache immutable variation id's not OPTLYVariation's which could go out-of-date across initialize's * Add getForcedVariation:userId: to Optimizely.m+.h * Add XCTAssert to testSetForcedVariationExperimentNotRunning * Add two tests against invalid experimentKey's * Add two tests against invalid variationKey's * Add testSetForcedVariationCalledOnInvalidUserId * Revert "Add OptimizelyBucketId" This reverts commit f8c60a8. * preferredVariationMap --> forcedVariationMap * Add '#pragma mark's to OPTLYDecisionServiceTest.m * Moving methods to different location, but not otherwise changing code * Add methods to OPTLYProjectConfigTest.m * Moving 4 methods to different section, OW code is unchanged. * Add testSetForcedVariationFollowedByGetForcedVariation * forcedVariationMap == userId --> experimentId --> variationId * @synchronized access to mutable forcedVariationMap * Add 2 new '@protocol Optimizely' methods to OPTLYClient.m
diff --git a/OptimizelySDKCore/OptimizelySDKCore/OPTLYDecisionService.m b/OptimizelySDKCore/OptimizelySDKCore/OPTLYDecisionService.m
@@ -60,6 +60,12 @@ - (OPTLYVariation *)getVariation:(NSString *)userId
         return nil;
     }
     
+    // ---- check for forced variation ----
+    bucketedVariation = [self.config getForcedVariation:experimentKey userId:userId];
+    if (bucketedVariation != nil) {
+        return bucketedVariation;
+    }
+
     // ---- check if the experiment is whitelisted ----
     if ([self checkWhitelistingForUser:userId experiment:experiment]) {
         return [self getWhitelistedVariationForUser:userId
diff --git a/OptimizelySDKCore/OptimizelySDKCore/OPTLYLoggerMessages.h b/OptimizelySDKCore/OptimizelySDKCore/OPTLYLoggerMessages.h
@@ -161,6 +161,8 @@ extern NSString *const OPTLYLoggerMessagesExperimentUnknownForExperimentId;
 extern NSString *const OPTLYLoggerMessagesExperimentUnknownForExperimentKey;
 extern NSString *const OPTLYLoggerMessagesGroupUnknownForGroupId;
 extern NSString *const OPTLYLoggerMessagesGetVariationNilVariation;
+extern NSString *const OPTLYLoggerMessagesVariationKeyUnknownForExperimentKey;
+extern NSString *const OPTLYLoggerMessagesProjectConfigUserIdInvalid;
 
 // ---- User Profile ----
 // debug
diff --git a/OptimizelySDKCore/OptimizelySDKCore/OPTLYLoggerMessages.m b/OptimizelySDKCore/OptimizelySDKCore/OPTLYLoggerMessages.m
@@ -156,6 +156,8 @@
 NSString *const OPTLYLoggerMessagesExperimentUnknownForExperimentKey = @"[PROJECT CONFIG] Experiment key not found for experiment: %@. Experiment key is not in the datafile.";  // experiment key
 NSString *const OPTLYLoggerMessagesGroupUnknownForGroupId = @"[PROJECT CONFIG] Group not found for group ID: %@. Group ID is not in the datafile."; // group id
 NSString *const OPTLYLoggerMessagesGetVariationNilVariation = @"[PROJECT CONFIG] Get variation returned a nil variation for user %@, experiment %@";
+NSString *const OPTLYLoggerMessagesVariationKeyUnknownForExperimentKey = @"[PROJECT CONFIG] Variation key %@ not found for experiment key %@.";
+NSString *const OPTLYLoggerMessagesProjectConfigUserIdInvalid = @"[PROJECT CONFIG] User ID cannot be an empty string.";
 
 // ---- User Profile ----
 // debug
diff --git a/OptimizelySDKCore/OptimizelySDKCore/OPTLYProjectConfig.h b/OptimizelySDKCore/OptimizelySDKCore/OPTLYProjectConfig.h
@@ -126,6 +126,19 @@ NS_ASSUME_NONNULL_END
  */
 - (nullable OPTLYVariable *)getVariableForVariableKey:(nonnull NSString *)variableKey;
 
+/**
+ * Get forced variation for a given experiment key and user id.
+ */
+- (nullable OPTLYVariation *)getForcedVariation:(nonnull NSString *)experimentKey
+                                         userId:(nonnull NSString *)userId;
+
+/**
+ * Set forced variation for a given experiment key and user id according to a given variation key.
+ */
+- (BOOL)setForcedVariation:(nonnull NSString *)experimentKey
+                    userId:(nonnull NSString *)userId
+              variationKey:(nonnull NSString *)variationKey;
+
 /**
  * Get variation for experiment and user ID with user attributes.
  */
diff --git a/OptimizelySDKCore/OptimizelySDKCore/OPTLYProjectConfig.m b/OptimizelySDKCore/OptimizelySDKCore/OPTLYProjectConfig.m
@@ -43,6 +43,9 @@ @interface OPTLYProjectConfig()
 @property (nonatomic, strong) NSDictionary<NSString *, OPTLYGroup *><Ignore> *groupIdToGroupMap;
 @property (nonatomic, strong) NSDictionary<NSString *, OPTLYAttribute *><Ignore> *attributeKeyToAttributeMap;
 @property (nonatomic, strong) NSDictionary<NSString *, OPTLYVariable *><Ignore> *variableKeyToVariableMap;
+//@property (nonatomic, strong) NSMutableDictionary<NSString *, NSMutableDictionary<NSString *, NSString *>><Ignore> *forcedVariationMap;
+//    userId --> experimentId --> variationId
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSMutableDictionary *><Ignore> *forcedVariationMap;
 
 @end
 
@@ -230,6 +233,82 @@ - (OPTLYVariable *)getVariableForVariableKey:(NSString *)variableKey {
     return variable;
 }
 
+#pragma mark -- Forced Variation Methods --
+
+- (OPTLYVariation *)getForcedVariation:(nonnull NSString *)experimentKey
+                                userId:(nonnull NSString *)userId {
+    // Get experiment from experimentKey .
+    OPTLYExperiment *experiment = [self getExperimentForKey:experimentKey];
+    if (!experiment) {
+        // NOTE: getExperimentForKey: will log any non-existent experimentKey and return experiment == nil for us.
+        return nil;
+    }
+    OPTLYVariation *variation = nil;
+    @synchronized (self.forcedVariationMap) {
+        NSMutableDictionary<NSString *, NSString *> *dictionary = self.forcedVariationMap[userId];
+        if (dictionary != nil) {
+            // Get variation from experimentId and variationId .
+            NSString *experimentId = experiment.experimentId;
+            NSString *variationId = dictionary[experimentId];
+            variation = [experiment getVariationForVariationId:variationId];
+        }
+    }
+    return variation;
+}
+
+- (BOOL)setForcedVariation:(nonnull NSString *)experimentKey
+                    userId:(nonnull NSString *)userId
+              variationKey:(nonnull NSString *)variationKey {
+    // Return YES if there were no errors, OW return NO .
+    // Get experiment from experimentKey .
+    OPTLYExperiment *experiment = [self getExperimentForKey:experimentKey];
+    if (!experiment) {
+        // NOTE: getExperimentForKey: will log any non-existent experimentKey and return experiment == nil for us.
+        return NO;
+    }
+    NSString *experimentId=experiment.experimentId;
+    // Check for valid userId
+    if ([userId length]==0) {
+        [self.logger logMessage:OPTLYLoggerMessagesProjectConfigUserIdInvalid withLevel:OptimizelyLogLevelDebug];
+        return NO;
+    }
+    // Get variation from experiment and non-nil variationKey, if applicable.
+    OPTLYVariation *variation = nil;
+    if (variationKey != nil) {
+        variation = [experiment getVariationForVariationKey:variationKey];
+        if (!variation) {
+            NSString *logMessage = [NSString stringWithFormat:OPTLYLoggerMessagesVariationKeyUnknownForExperimentKey, variationKey, experimentKey];
+            [self.logger logMessage:logMessage withLevel:OptimizelyLogLevelDebug];
+            // Leave in current state, and report NO meaning there was an error.
+            return NO;
+        }
+    }
+    @synchronized (self.forcedVariationMap) {
+        // Locate relevant dictionary inside forcedVariationMap
+        NSMutableDictionary<NSString *, NSString *> *dictionary = self.forcedVariationMap[userId];
+        if ((dictionary == nil) && (variationKey != nil)) {
+            // We need a non-nil dictionary to store an OPTLYVariation .
+            dictionary = [[NSMutableDictionary alloc] init];
+            self.forcedVariationMap[userId] = dictionary;
+        }
+        // Apply change to dictionary
+        if (variation == nil) {
+            // NOTE: removeObjectForKey: "Does nothing if [experimentKey] does not exist."
+            // https://developer.apple.com/documentation/foundation/nsmutabledictionary/1416518-removeobjectforkey?language=objc
+            [dictionary removeObjectForKey:experimentId];
+            if ([dictionary count] == 0) {
+                // For elegance, we can remove empty dictionary for userId from self.forcedVariationMap
+                [self.forcedVariationMap removeObjectForKey:userId];
+            }
+        } else {
+            // If there is no OPTLYExperiment *experiment corresponding to experimentKey ,
+            // then we will land in the "(variation == nil)" case above due to code above.
+            dictionary[experimentId] = variation.variationId;
+        };
+    };
+    return YES;
+}
+
 #pragma mark -- Property Getters --
 
 - (NSArray *)allExperiments
@@ -313,6 +392,16 @@ - (NSDictionary *)eventKeyToEventMap {
     return _variableKeyToVariableMap;
 }
 
+//- (NSMutableDictionary<NSString *, NSMutableDictionary<NSString *, NSString *>> *)forcedVariationMap {
+- (NSMutableDictionary<NSString *, NSMutableDictionary *> *)forcedVariationMap {
+    @synchronized (self) {
+        if (!_forcedVariationMap) {
+            _forcedVariationMap = [[NSMutableDictionary alloc] init];
+        }
+    }
+    return _forcedVariationMap;
+}
+
 #pragma mark -- Generate Mappings --
 
 - (NSDictionary *)generateAudienceIdToAudienceMap
diff --git a/OptimizelySDKCore/OptimizelySDKCore/Optimizely.h b/OptimizelySDKCore/OptimizelySDKCore/Optimizely.h
@@ -95,6 +95,39 @@ typedef NS_ENUM(NSInteger, OPTLYLiveVariableError) {
                                 userId:(nonnull NSString *)userId
                             attributes:(nullable NSDictionary<NSString *, NSString *> *)attributes;
 
+#pragma mark - Forced Variation Methods
+/**
+ * Use the setForcedVariation method to force an experimentKey-userId
+ * pair into a specific variation for QA purposes.
+ * The forced bucketing feature allows customers to force users into
+ * variations in real time for QA purposes without requiring datafile
+ * downloads from the network. Methods activate and track are called
+ * as usual after the variation is set, but the user will be bucketed
+ * into the forced variation overriding any variation which would be
+ * computed via the network datafile.
+ */
+
+/**
+ * Return forced variation for experiment and user ID.
+ * @param experimentKey The key for the experiment.
+ * @param userId The user ID to be used for bucketing.
+ * @return forced variation if it exists, otherwise return nil.
+ */
+- (OPTLYVariation *_Nullable)getForcedVariation:(nonnull NSString *)experimentKey
+                                         userId:(nonnull NSString *)userId;
+
+/**
+ * Set forced variation for experiment and user ID to variationKey.
+ * @param experimentKey The key for the experiment.
+ * @param userId The user ID to be used for bucketing.
+ * @param variationKey The variation the user should be forced into.
+ * This value can be nil, in which case, the forced variation is cleared.
+ * @return YES if there were no errors, otherwise return NO.
+ */
+- (BOOL)setForcedVariation:(nonnull NSString *)experimentKey
+                    userId:(nonnull NSString *)userId
+              variationKey:(nullable NSString *)variationKey;
+
 #pragma mark - trackEvent methods
 /**
  * Track an event
diff --git a/OptimizelySDKCore/OptimizelySDKCore/Optimizely.m b/OptimizelySDKCore/OptimizelySDKCore/Optimizely.m
@@ -194,6 +194,21 @@ - (OPTLYVariation *)variation:(NSString *)experimentKey
     return bucketedVariation;
 }
 
+#pragma mark Forced variation methods
+- (OPTLYVariation *)getForcedVariation:(nonnull NSString *)experimentKey
+                                userId:(nonnull NSString *)userId {
+    return [self.config getForcedVariation:experimentKey
+                                    userId:userId];
+}
+
+- (BOOL)setForcedVariation:(nonnull NSString *)experimentKey
+                    userId:(nonnull NSString *)userId
+              variationKey:(nullable NSString *)variationKey {
+    return [self.config setForcedVariation:experimentKey
+                                    userId:userId
+                              variationKey:variationKey];
+}
+
 #pragma mark trackEvent methods
 - (void)track:(NSString *)eventKey userId:(NSString *)userId
 {
diff --git a/OptimizelySDKCore/OptimizelySDKCoreTests/OPTLYDecisionServiceTest.m b/OptimizelySDKCore/OptimizelySDKCoreTests/OPTLYDecisionServiceTest.m
diff --git a/OptimizelySDKCore/OptimizelySDKCoreTests/OPTLYProjectConfigTest.m b/OptimizelySDKCore/OptimizelySDKCoreTests/OPTLYProjectConfigTest.m
diff --git a/OptimizelySDKShared/OptimizelySDKShared/OPTLYClient.m b/OptimizelySDKShared/OptimizelySDKShared/OPTLYClient.m
