CORE-1521 optional partner parameters for FB

Author: echo-branch

Branch-SDK/BNCPartnerParameters.h

@@ -0,0 +1,31 @@
+//
+//  BNCPartnerParameters.h
+//  Branch
+//
+//  Created by Ernest Cho on 12/9/20.
+//  Copyright © 2020 Branch, Inc. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Parameters that clients wish to share with partners
+ */
+@interface BNCPartnerParameters : NSObject
+
++ (instancetype)shared;
+
+// FB partner parameters, see FB documentation for details
+// Values that do not looks like a valid SHA-256 hash are ignored
+- (void)addFaceBookParameterWithName:(NSString *)name value:(NSString *)value;
+
+- (void)clearAllParameters;
+
+// reference to the internal json dictionary
+- (NSDictionary *)parameterJson;
+
+@end
+
+NS_ASSUME_NONNULL_END

Branch-SDK/BNCPartnerParameters.m

@@ -0,0 +1,73 @@
+//
+//  BNCPartnerParameters.m
+//  Branch
+//
+//  Created by Ernest Cho on 12/9/20.
+//  Copyright © 2020 Branch, Inc. All rights reserved.
+//
+
+#import "BNCPartnerParameters.h"
+
+@interface BNCPartnerParameters()
+@property (nonatomic, strong, readwrite) NSMutableDictionary<NSString *, NSMutableDictionary<NSString *, NSString *> *> *parameters;
+@end
+
+@implementation BNCPartnerParameters
+
++ (instancetype)shared {
+    static BNCPartnerParameters *partnerParameters;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        partnerParameters = [BNCPartnerParameters new];
+    });
+    return partnerParameters;
+}
+
+- (instancetype)init {
+    self = [super init];
+    if (self) {
+        self.parameters = [NSMutableDictionary<NSString *, NSMutableDictionary<NSString *, NSString *> *> new];
+    }
+    return self;
+}
+
+- (void)clearAllParameters {
+    self.parameters = [NSMutableDictionary<NSString *, NSMutableDictionary<NSString *, NSString *> *> new];
+}
+
+- (NSMutableDictionary<NSString *, NSString *> *)parametersForPartner:(NSString *)partnerName {
+    NSMutableDictionary<NSString *, NSString *> *parametersForPartner = [self.parameters objectForKey:partnerName];
+    if (!parametersForPartner) {
+        parametersForPartner = [NSMutableDictionary<NSString *, NSString *> new];
+        [self.parameters setObject:parametersForPartner forKey:partnerName];
+    }
+    return parametersForPartner;
+}
+
+- (void)addParameterWithName:(NSString *)name value:(NSString *)value partnerName:(NSString *)partnerName {
+    NSMutableDictionary<NSString *, NSString *> *parametersForPartner = [self parametersForPartner:partnerName];
+    [parametersForPartner setObject:value forKey:name];
+}
+
+- (void)addFaceBookParameterWithName:(NSString *)name value:(NSString *)value {
+    if ([self sha256HashSanityCheckValue:value]) {
+        [self addParameterWithName:name value:value partnerName:@"fb"];
+    } else {
+        // TODO: log a warning that the parameter looks invalid and will be ignored. Do not log the value as it may be PII that was inadvertently passed in.
+    }
+}
+
+- (BOOL)sha256HashSanityCheckValue:(NSString *)value {
+    return ([value length] == 64 && [self isStringHex:value]);
+}
+
+- (BOOL)isStringHex:(NSString *)string {
+    NSCharacterSet *chars = [[NSCharacterSet characterSetWithCharactersInString:@"0123456789ABCDEF"] invertedSet];
+    return (NSNotFound == [[string uppercaseString] rangeOfCharacterFromSet:chars].location);
+}
+
+- (NSDictionary *)parameterJson {
+    return self.parameters;
+}
+
+@end

Branch-SDK/Branch.h

@@ -690,6 +690,19 @@ typedef NS_ENUM(NSUInteger, BranchCreditHistoryOrder) {
  */
 - (void)setSKAdNetworkCalloutMaxTimeSinceInstall:(NSTimeInterval)maxTimeInterval;
 
+/*
+ Add a Partner Parameter for Facebook.
+ Once set, this parameter is attached to install, opens and events until cleared or the app restarts.
+ 
+ See Facebook's documentation for details on valid parameters
+ */
+- (void)addFacebookPartnerParameterWithName:(NSString *)name value:(NSString *)value;
+
+/**
+ Clears all Partner Parameters
+ */
+- (void)clearPartnerParameters;
+
 /**
  Specify the time to wait in seconds between retries in the case of a Branch server error
 

Branch-SDK/Branch.m

@@ -43,6 +43,7 @@
 #import "BNCCallbackMap.h"
 #import "BNCSKAdNetwork.h"
 #import "BNCAppGroupsData.h"
+#import "BNCPartnerParameters.h"
 
 #if !TARGET_OS_TV
 #import "BNCUserAgentCollector.h"
@@ -972,6 +973,16 @@ - (void)setSKAdNetworkCalloutMaxTimeSinceInstall:(NSTimeInterval)maxTimeInterval
     [BNCSKAdNetwork sharedInstance].maxTimeSinceInstall = maxTimeInterval;
 }
 
+#pragma mark - Partner Parameters
+
+- (void)clearPartnerParameters {
+    [[BNCPartnerParameters shared] clearAllParameters];
+}
+
+- (void)addFacebookPartnerParameterWithName:(NSString *)name value:(NSString *)value {
+    [[BNCPartnerParameters shared] addFaceBookParameterWithName:name value:value];
+}
+
 #pragma mark - Pre-initialization support
 
 - (void) dispatchToIsolationQueue:(dispatch_block_t) initBlock {

Branch-SDK/BranchConstants.h

@@ -73,6 +73,7 @@ extern NSString * const BRANCH_REQUEST_KEY_LATEST_APP_CLIP_INSTALL_TIME;
 extern NSString * const BRANCH_REQUEST_KEY_APP_CLIP_RANDOMIZED_DEVICE_TOKEN;
 extern NSString * const BRANCH_REQUEST_KEY_APP_CLIP_RANDOMIZED_BUNDLE_TOKEN;
 
+extern NSString * const BRANCH_REQUEST_KEY_PARTNER_PARAMETERS;
 
 extern NSString * const BRANCH_REQUEST_ENDPOINT_SET_IDENTITY;
 extern NSString * const BRANCH_REQUEST_ENDPOINT_APP_LINK_SETTINGS;

Branch-SDK/BranchConstants.m

@@ -68,6 +68,8 @@
 NSString * const BRANCH_REQUEST_KEY_APP_CLIP_RANDOMIZED_DEVICE_TOKEN = @"app_clip_randomized_device_token";
 NSString * const BRANCH_REQUEST_KEY_APP_CLIP_RANDOMIZED_BUNDLE_TOKEN = @"app_clip_randomized_bundle_token";
 
+NSString * const BRANCH_REQUEST_KEY_PARTNER_PARAMETERS = @"partner_data";
+
 NSString * const BRANCH_REQUEST_ENDPOINT_SET_IDENTITY = @"profile";
 NSString * const BRANCH_REQUEST_ENDPOINT_APP_LINK_SETTINGS = @"app-link-settings";
 NSString * const BRANCH_REQUEST_ENDPOINT_LOGOUT = @"logout";

Branch-SDK/BranchEvent.m

@@ -11,6 +11,7 @@
 #import "BNCCallbackMap.h"
 #import "BNCReachability.h"
 #import "BNCSKAdNetwork.h"
+#import "BNCPartnerParameters.h"
 
 #pragma mark BranchStandardEvents
 
@@ -301,6 +302,12 @@ - (NSDictionary *)buildEventDictionary {
     if (contentItemDictionaries.count) {
         eventDictionary[@"content_items"] = contentItemDictionaries;
     }
+    
+    NSDictionary *partnerParameters = [[BNCPartnerParameters shared] parameterJson];
+    if (partnerParameters.count > 0) {
+        eventDictionary[BRANCH_REQUEST_KEY_PARTNER_PARAMETERS] = partnerParameters;
+    }
+    
     return eventDictionary;
 }
 

Branch-SDK/BranchInstallRequest.m

@@ -14,6 +14,7 @@
 #import "BNCApplication.h"
 #import "BNCAppleReceipt.h"
 #import "BNCAppGroupsData.h"
+#import "BNCPartnerParameters.h"
 
 @implementation BranchInstallRequest
 
@@ -48,6 +49,11 @@ - (void)makeRequest:(BNCServerInterface *)serverInterface key:(NSString *)key ca
         [self safeSetValue:[BNCAppGroupsData shared].bundleToken forKey:BRANCH_REQUEST_KEY_APP_CLIP_RANDOMIZED_BUNDLE_TOKEN onDict:params];
     }
 
+    NSDictionary *partnerParameters = [[BNCPartnerParameters shared] parameterJson];
+    if (partnerParameters.count > 0) {
+        [self safeSetValue:partnerParameters forKey:BRANCH_REQUEST_KEY_PARTNER_PARAMETERS onDict:params];
+    }
+        
     params[BRANCH_REQUEST_KEY_DEBUG] = @(preferenceHelper.isDebug);
 
     if (preferenceHelper.appleSearchAdNeedsSend) {

Branch-SDK/BranchOpenRequest.m

@@ -20,6 +20,7 @@
 #import "BNCTuneUtility.h"
 #import "BNCSKAdNetwork.h"
 #import "BNCAppGroupsData.h"
+#import "BNCPartnerParameters.h"
 
 @interface BranchOpenRequest ()
 @property (assign, nonatomic) BOOL isInstall;
@@ -85,6 +86,11 @@ - (void)makeRequest:(BNCServerInterface *)serverInterface key:(NSString *)key ca
                     forKey:BRANCH_REQUEST_KEY_SEARCH_AD
                     onDict:params];
     }
+    
+    NSDictionary *partnerParameters = [[BNCPartnerParameters shared] parameterJson];
+    if (partnerParameters.count > 0) {
+        [self safeSetValue:partnerParameters forKey:BRANCH_REQUEST_KEY_PARTNER_PARAMETERS onDict:params];
+    }
 
     BNCApplication *application = [BNCApplication currentApplication];
     params[@"lastest_update_time"] = BNCWireFormatFromDate(application.currentBuildDate);