targetingFromCache and targetingClearCache APIs (#19)

- targeting API now also caches returned keyvalues to client storage
- targetingFromCache will fetch previously cached keyvalues from client
  storage. Contrary to the targeting API, it does not block and is
  synchronous.
- targetingClearCache will clear any previously cached keyvalues
- Update demo-ios-{objc,swift} to show usage of targetingFromCache
- Update demo-ios-{objc,swift} to show usage of targetingClearCache
- Update README with targeting*Cache docs

Author: bmilekic

README.md

@@ -144,6 +144,25 @@ do {
 
 On success, the resulting key values are typically sent as part of a subsequent ad call. Therefore we recommend that you either call `targeting()` before each ad call, or in parallel periodically, caching the resulting key values which you then provide in ad calls.
 
+#### Caching Targeting Data
+
+The `targeting` API will automatically cache resulting key value data in client storage on success. You can subsequently retrieve the cached key value data as follows:
+
+```swift
+let cachedTargetingData = OPTABLE!.targetingFromCache()
+if (cachedTargetingData != nil) {
+  // cachedTargetingData! is an NSDictionary which you can cast as! [String: Any]
+}
+```
+
+You can also clear the locally cached targeting data:
+
+```swift
+OPTABLE!.targetingClearCache()
+```
+
+Note that both `targetingFromCache()` and `targetingClearCache()` are synchronous.
+
 ### Witness API
 
 To send real-time event data from the user's device to the sandbox for eventual audience assembly, you can call the witness API as follows:
@@ -310,6 +329,30 @@ NSError *error = nil;
 [OPTABLE targetingAndReturnError:&error];
 ```
 
+#### Caching Targeting Data
+
+The `targetingAndReturnError` method will automatically cache resulting key value data in client storage on success. You can subsequently retrieve the cached key value data as follows:
+
+```objective-c
+@import OptableSDK;
+...
+NSDictionary *cachedTargetingData = nil;
+cachedTargetingData = [OPTABLE targetingFromCache];
+if (cachedTargetingData != nil) {
+  // cachedTargetingData! is an NSDictionary
+}
+```
+
+You can also clear the locally cached targeting data:
+
+```objective-c
+@import OptableSDK;
+...
+[OPTABLE targetingClearCache];
+```
+
+Note that both `targetingFromCache` and `targetingClearCache` are synchronous.
+
 ### Witness API
 
 To send real-time event data from the user's device to the sandbox for eventual audience assembly, you can call the witness API as follows:

Source/Core/LocalStorage.swift

@@ -12,13 +12,16 @@
 import Foundation
 
 class LocalStorage: NSObject {
-    let keyPfx: String = "OPTABLE_"
+    let keyPfx: String = "OPTABLE"
     var passportKey: String
+    var targetingKey: String
 
     init(_ config: Config) {
-        // The key used for storing the passport should be unique to the host+app that this instance was initialized with:
-        let utf8str = (config.host + "/" + config.app).data(using: .utf8)
-        self.passportKey = self.keyPfx + utf8str!.base64EncodedString(options: Data.Base64EncodingOptions(rawValue: 0))
+        // The key used for storage should be unique to the host+app that this instance was initialized with:
+        let utf8str = (config.host + "/" + config.app).data(using: .utf8)!.base64EncodedString(options: Data.Base64EncodingOptions(rawValue: 0))
+
+        self.passportKey = self.keyPfx + "_PASS_" + utf8str
+        self.targetingKey = self.keyPfx + "_TGT_" + utf8str
     }
 
     func getPassport() -> String? {
@@ -27,5 +30,17 @@ class LocalStorage: NSObject {
 
     func setPassport(_ passport: String) -> Void {
         UserDefaults.standard.set(passport, forKey: passportKey)
-    }    
+    }
+
+    func getTargeting() -> [String: Any]? {
+        return UserDefaults.standard.dictionary(forKey: targetingKey)
+    }
+
+    func setTargeting(_ keyvalues: [String: Any]) -> Void {
+        UserDefaults.standard.setValue(keyvalues, forKey: targetingKey)
+    }
+
+    func clearTargeting() -> Void {
+        UserDefaults.standard.removeObject(forKey: targetingKey)
+    }
 }

Source/Edge/Targeting.swift

@@ -2,7 +2,8 @@
 //  Targeting.swift
 //  OptableSDK
 //
-//  Created by Bosko Milekic on 2020-08-26.
+//  Copyright © 2020 Optable Technologies, Inc. All rights reserved.
+//  See LICENSE for details.
 //
 
 import Foundation

Source/OptableSDK.swift

@@ -170,6 +170,9 @@ public class OptableSDK: NSObject {
     //  The targeting method is asynchronous, and on completion it will call the specified completion handler,
     //  passing it either the NSDictionary targeting data on success, or an OptableError on failure.
     //
+    //  On success, this method will also cache the resulting targeting data in client storage, which can
+    //  be access using targetingFromCache(), and cleared using targetingClearCache().
+    //
     public func targeting(_ completion: @escaping (Result<NSDictionary,OptableError>) -> Void) throws -> Void {
         try Targeting(config: self.config, client: self.client) { (data, response, error) in
             guard let response = response as? HTTPURLResponse, error == nil else {
@@ -187,7 +190,12 @@ public class OptableSDK: NSObject {
             }
 
             do {
-                let result = try JSONSerialization.jsonObject(with: data!, options: []) as? NSDictionary
+                let keyvalues = try JSONSerialization.jsonObject(with: data!, options: [])
+                let result = keyvalues as? NSDictionary
+
+                // We cache the latest targeting result in client storage for targetingFromCache() users:
+                self.client.storage.setTargeting(keyvalues as! [String: Any])
+
                 completion(.success(result!))
             } catch {
                 completion(.failure(OptableError.targeting("Error parsing JSON response: \(error)")))
@@ -213,6 +221,26 @@ public class OptableSDK: NSObject {
         }
     }
 
+    //
+    //  targetingFromCache() returns the previously cached targeting data, if any.
+    //
+    @objc
+    public func targetingFromCache() -> NSDictionary? {
+        let keyvalues = self.client.storage.getTargeting()
+        if (keyvalues == nil) {
+            return nil
+        }
+        return (keyvalues! as NSDictionary)
+    }
+
+    //
+    //  targetingClearCache() clears any previously cached targeting data.
+    //
+    @objc
+    public func targetingClearCache() -> Void {
+        self.client.storage.clearTargeting()
+    }
+
     //
     //  witness(event, properties, completion) calls the Optable Sandbox "witness" API in order to log
     //  a specified 'event' (e.g., "app.screenView", "ui.buttonPressed"), with the specified keyvalue

demo-ios-objc/Podfile.lock

@@ -1,5 +1,5 @@
 PODS:
-  - Google-Mobile-Ads-SDK (7.67.1):
+  - Google-Mobile-Ads-SDK (7.68.0):
     - GoogleAppMeasurement (~> 7.0)
     - GoogleUserMessagingPlatform (~> 1.1)
   - GoogleAppMeasurement (7.0.0):
@@ -52,7 +52,7 @@ EXTERNAL SOURCES:
     :path: "../"
 
 SPEC CHECKSUMS:
-  Google-Mobile-Ads-SDK: 4c11bba9a823ed16c42f14d42feebc7678fbfd6a
+  Google-Mobile-Ads-SDK: 29bbdb182d69ff606cc0301da1590b40be8d2205
   GoogleAppMeasurement: 7790ef975d1d463c8614cd949a847e612edf087a
   GoogleUserMessagingPlatform: 1d4b6946710d18cec34742054092e2c2bddae61f
   GoogleUtilities: ffb2f4159f2c897c6e8992bd7fbcdef8a300589c

demo-ios-objc/demo-ios-objc/Base.lproj/Main.storyboard

@@ -2,7 +2,7 @@
 <document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="17156" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="9KB-Po-ioE">
     <device id="retina6_1" orientation="portrait" appearance="light"/>
     <dependencies>
-        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="17125"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="17126"/>
         <capability name="Safe area layout guides" minToolsVersion="9.0"/>
         <capability name="System colors in document resources" minToolsVersion="11.0"/>
         <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
@@ -43,7 +43,7 @@
                                         <rect key="frame" x="0.0" y="138" width="374" height="30"/>
                                         <state key="normal" title="Identify"/>
                                         <connections>
-                                            <action selector="dispatchIdentify:" destination="BYZ-38-t0r" eventType="touchUpInside" id="Sae-rS-iHh"/>
+                                            <action selector="dispatchIdentify:" destination="BYZ-38-t0r" eventType="touchUpInside" id="CNy-Db-Mwd"/>
                                         </connections>
                                     </button>
                                 </subviews>
@@ -92,30 +92,52 @@
                         <subviews>
                             <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="x4k-D7-Mvh">
                                 <rect key="frame" x="50" y="94" width="314" height="30"/>
-                                <state key="normal" title="Load Banner"/>
+                                <state key="normal" title="Load Targeting and Banner"/>
                                 <connections>
-                                    <action selector="loadBannerWithTargeting:" destination="qnL-ha-uwz" eventType="touchUpInside" id="hBs-SW-Fgz"/>
+                                    <action selector="loadBannerWithTargeting:" destination="qnL-ha-uwz" eventType="touchUpInside" id="2sa-1R-eGT"/>
                                 </connections>
                             </button>
                             <textView clipsSubviews="YES" multipleTouchEnabled="YES" contentMode="scaleToFill" fixedFrame="YES" textAlignment="natural" translatesAutoresizingMaskIntoConstraints="NO" id="c00-PY-Cdm">
-                                <rect key="frame" x="50" y="157" width="314" height="370"/>
+                                <rect key="frame" x="50" y="210" width="314" height="401"/>
                                 <autoresizingMask key="autoresizingMask" flexibleMaxX="YES" flexibleMaxY="YES"/>
                                 <color key="backgroundColor" systemColor="systemBackgroundColor"/>
                                 <color key="textColor" systemColor="labelColor"/>
                                 <fontDescription key="fontDescription" type="system" pointSize="14"/>
                                 <textInputTraits key="textInputTraits" autocapitalizationType="sentences"/>
                             </textView>
+                            <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="hXv-1T-mbc">
+                                <rect key="frame" x="50" y="126" width="314" height="30"/>
+                                <state key="normal" title="Cached Targeting and Banner"/>
+                                <connections>
+                                    <action selector="loadBannerWithTargetingFromCache:" destination="qnL-ha-uwz" eventType="touchUpInside" id="dWK-eA-gis"/>
+                                </connections>
+                            </button>
+                            <button opaque="NO" contentMode="scaleToFill" contentHorizontalAlignment="center" contentVerticalAlignment="center" buttonType="system" lineBreakMode="middleTruncation" translatesAutoresizingMaskIntoConstraints="NO" id="1Jw-Ws-T0T">
+                                <rect key="frame" x="50" y="158" width="314" height="30"/>
+                                <state key="normal" title="Clear Targeting Cache"/>
+                                <connections>
+                                    <action selector="clearTargetingCache:" destination="qnL-ha-uwz" eventType="touchUpInside" id="Ll8-bx-lvM"/>
+                                </connections>
+                            </button>
                         </subviews>
                         <viewLayoutGuide key="safeArea" id="Cyy-8b-GCg"/>
                         <color key="backgroundColor" systemColor="systemBackgroundColor"/>
                         <constraints>
+                            <constraint firstItem="1Jw-Ws-T0T" firstAttribute="top" secondItem="hXv-1T-mbc" secondAttribute="bottom" constant="2" id="C0X-HG-eYe"/>
+                            <constraint firstItem="hXv-1T-mbc" firstAttribute="top" secondItem="x4k-D7-Mvh" secondAttribute="bottom" constant="2" id="D1p-oM-m1D"/>
+                            <constraint firstItem="1Jw-Ws-T0T" firstAttribute="leading" secondItem="Cyy-8b-GCg" secondAttribute="leading" constant="50" id="Kbz-TZ-d9K"/>
+                            <constraint firstItem="Cyy-8b-GCg" firstAttribute="trailing" secondItem="hXv-1T-mbc" secondAttribute="trailing" constant="50" id="Qrd-np-QV1"/>
+                            <constraint firstItem="hXv-1T-mbc" firstAttribute="leading" secondItem="Cyy-8b-GCg" secondAttribute="leading" constant="50" id="XW9-qT-dp9"/>
                             <constraint firstItem="x4k-D7-Mvh" firstAttribute="top" secondItem="Cyy-8b-GCg" secondAttribute="top" constant="50" id="djs-hu-hJD"/>
+                            <constraint firstItem="Cyy-8b-GCg" firstAttribute="trailing" secondItem="1Jw-Ws-T0T" secondAttribute="trailing" constant="50" id="haI-Rw-Lg7"/>
                             <constraint firstItem="Cyy-8b-GCg" firstAttribute="trailing" secondItem="x4k-D7-Mvh" secondAttribute="trailing" constant="50" id="mJB-PI-zyh"/>
                             <constraint firstItem="x4k-D7-Mvh" firstAttribute="leading" secondItem="Cyy-8b-GCg" secondAttribute="leading" constant="50" id="wPd-LN-GBn"/>
                         </constraints>
                     </view>
                     <tabBarItem key="tabBarItem" title="GAM Banner" image="rectangle.3.offgrid.fill" catalog="system" selectedImage="rectangle.3.offgrid.fill" id="WaP-P0-dwN"/>
                     <connections>
+                        <outlet property="cachedBannerButton" destination="hXv-1T-mbc" id="G6q-wE-nPC"/>
+                        <outlet property="clearTargetingCacheButton" destination="1Jw-Ws-T0T" id="Kk2-ip-LUl"/>
                         <outlet property="loadBannerButton" destination="x4k-D7-Mvh" id="Yre-Zn-37w"/>
                         <outlet property="targetingOutput" destination="c00-PY-Cdm" id="qBw-qG-iVR"/>
                     </connections>

demo-ios-objc/demo-ios-objc/GAMBannerViewController.h

@@ -10,8 +10,9 @@
 
 @interface GAMBannerViewController : UIViewController
 @property (weak, nonatomic) IBOutlet UIButton *loadBannerButton;
+@property (weak, nonatomic) IBOutlet UIButton *cachedBannerButton;
+@property (weak, nonatomic) IBOutlet UIButton *clearTargetingCacheButton;
 @property (weak, nonatomic) IBOutlet UITextView *targetingOutput;
 
 - (IBAction)loadBannerWithTargeting:(id)sender;
 @end
-

demo-ios-objc/demo-ios-objc/GAMBannerViewController.m

@@ -31,7 +31,7 @@ - (void)viewDidLoad {
     delegate.targetingOutput = self.targetingOutput;
 }
 
-- (void)loadBannerWithTargeting:(id)sender {
+- (IBAction)loadBannerWithTargeting:(id)sender {
     NSError *error = nil;
 
     [_targetingOutput setText:@"Calling /targeting API...\n\n"];
@@ -40,6 +40,33 @@ - (void)loadBannerWithTargeting:(id)sender {
     [OPTABLE witness:@"GAMBannerViewController.loadBannerClicked" properties:@{ @"example": @"value" } error:&error];
 }
 
+- (IBAction)loadBannerWithTargetingFromCache:(id)sender {
+    NSError *error = nil;
+    DFPRequest *request = [DFPRequest request];
+    NSDictionary *keyvals = nil;
+
+    [_targetingOutput setText:@"Checking local targeting cache...\n\n"];
+
+    keyvals = [OPTABLE targetingFromCache];
+
+    if (keyvals != nil) {
+        request.customTargeting = keyvals;
+        NSLog(@"[OptableSDK] Cached targeting values found: %@", keyvals);
+        [_targetingOutput setText:[NSString stringWithFormat:@"%@\nFound cached data: %@\n", [_targetingOutput text], keyvals]];
+    } else {
+        [_targetingOutput setText:[NSString stringWithFormat:@"%@\nCache empty.\n",
+            [_targetingOutput text]]];
+    }
+
+    [self.bannerView loadRequest:request];
+    [OPTABLE witness:@"GAMBannerViewController.loadBannerClicked" properties:@{ @"example": @"value" } error:&error];
+}
+
+- (IBAction)clearTargetingCache:(id)sender {
+    [_targetingOutput setText:@"Clearing local targeting cache.\n\n"];
+    [OPTABLE targetingClearCache];
+}
+
 - (void)addBannerViewToView:(UIView *)bannerView {
     bannerView.translatesAutoresizingMaskIntoConstraints = NO;
     [self.view addSubview:bannerView];

demo-ios-objc/demo-ios-objc/IdentifyViewController.h

@@ -16,4 +16,3 @@
 
 - (IBAction)dispatchIdentify:(id)sender;
 @end
-

demo-ios-objc/demo-ios-objc/IdentifyViewController.m

@@ -23,7 +23,7 @@ - (void)viewDidLoad {
     delegate.identifyOutput = self.identifyOutput;
 }
 
-- (void)dispatchIdentify:(id)sender {
+- (IBAction)dispatchIdentify:(id)sender {
     NSString *email = [_identifyInput text];
     bool aaid = [_identifyIDFA isOn];
     NSMutableString *output;