README.md 9.59 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
# Installation with CocoaPods

[CocoaPods](http://cocoapods.org) is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries. You can install it with the following command:

```bash
$ gem install cocoapods
```


# Installation

12
Add PrimedIO pod to `Podfile`
13
```ruby
14
pod 'PrimedIO', '~> <VERSION>'
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
```

Then, run the following command:

```ruby
pod install
```

## If using Swift you need to add Bridge Header
### Add new header file
Click on File -> New -> File… and select “Header File” in the “Source” tab.

### Name Header File
Name this file Bridging-Header.h

###  Locate Header File in Build Settings
Open your project Build Settings and search for “Bridging”. Edit the key “Objective-C Bridging Header” to project_name/Bridging-Header.h

### Import pod
You are now ready to add your imports into your Bridging-Header.h file for the pods you want to use.
```objective-c
#ifndef Bridging_Header_h
#define Bridging_Header_h

Bosko Petreski's avatar
Bosko Petreski committed
39 40
#import <PrimedIO/Primed.h>
#import <PrimedIO/PrimedTracker.h>
41 42 43 44

#endif /* Bridging_Header_h */
```

45 46
# Usage Primed Tracker
## Initialisation
47
```objective-c
48 49
[PrimedTracker.sharedInstance initWithPublicKey:@"somekey" secretKey:@"somesecretkeywithalotofchars" connectionString:@"API_URL_GO_HERE" trackingConnectionString:@"WEBSOCKET_URL_GO_HERE" heartbeatInterval:10 eventQueueRetryInterval:10];
```
50
**customBasicProperties**
51
Add custom basic properties.
52
```objective-c
Bosko Petreski's avatar
Bosko Petreski committed
53
PrimedTracker.sharedInstance.customBasicProperties = @{@"name":@"Joe",@"age":@"32"};
54
```
55

56
## Track events
57 58 59 60 61
**trackClick**
Sends a click event to Primed.
```objective-c
-(void)trackClick:(NSInteger)x y:(NSInteger)y interactionType:(InteractionType)interactionType;
-(void)trackClick:(NSInteger)x y:(NSInteger)y;
62
```
63 64 65 66

**trackView**
Sends a view event to Primed. The event requires at least a unique identifier (`uri`) for the page, or view that the user is viewing. The `uri` can be a typical web url (e.g. `http://example.com/articles/1`), or it can indicate a hierarchical view identifer (e.g. `app.views.settings`). Additionally, the call expects a `customProperties` `NSDictionary`, which holds user-defined key-value properties. The keys are always `NSString` and values can be any (boxed) primitive type (`NSInteger`, `NSFloat`, `NSString`, etc.).
```objective-c
67
-(void)trackView:(NSString *)uri customProperties:(NSDictionary<NSString*,id> *)customProperties;
68
-(void)trackView:(NSString *)uri;
69 70 71 72 73
```

**trackScroll**
Sends a scroll event to Primed. The event requires a `ScrollDirection` argument, which indicates whether the user scrolled up, down, left or right and a `distance` in pixels.
```objective-c
74
-(void)trackScroll:(ScrollDirection)scrollDirection distance:(NSInteger)distance;
75 76 77 78 79
```

**trackEnterViewport**
Sends an enterViewPort event to Primed. This event is generally called whenever an items appears into view for the user. the call expects a `customProperties` NSDictionary, which holds user-defined key-value properties. The keys are always `NSString` and values can be any (boxed) primitive type (`NSInteger`, `NSFloat`, `NSString`, etc.).
```objective-c
80
-(void)trackEnterViewPort:customProperties:(NSDictionary<NSString*,id> *)customProperties;
81 82 83 84 85
```

**trackExitViewport**
Sends an exitViewPort event to Primed. This event is generally called whenever an items disappears from view for the user. the call expects a `customProperties` NSDictionary, which holds user-defined key-value properties. The keys are always `NSString` and values can be any (boxed) primitive type (`NSInteger`, `NSFloat`, `NSString`, etc.).
```objective-c
86
-(void)trackExitViewPort:(NSDictionary<NSString*,id> *)customProperties;
87 88 89 90 91
```

**trackPositionChange**
Sends a positionChange event to Primed.
```objective-c
92
-(void)trackPositionChange:(CLLocation *)location;
93 94 95 96 97
```

**trackStart**
Sends a start event to Primed. The event requires at least a unique identifier (`uri`) for the page, or view that the user entered the application on (usually the start or homepage). The `uri` can be a typical web url (e.g. `http://example.com/articles/1`), or it can indicate a hierarchical view identifer (e.g. `app.views.settings`). Additionally, the call expects a `customProperties` NSDictionary, which holds user-defined key-value properties. The keys are always `NSString` and values can be any (boxed) primitive type (`NSInteger`, `NSFloat`, `NSString`, etc.).
```objective-c
98
-(void)trackStart:(NSString *)uri customProperties:(NSDictionary<NSString*,id> *)customProperties;
99
-(void)trackStart:(NSString *)uri;
100 101 102 103 104
```

**trackEnd**
Sends a end event to Primed. The event expects no arguments.
```objective-c
105
-(void)trackEnd;
106 107 108 109
```

**trackCustomEvent**
User defined event. For example defining a custom `VIDEOSTART` event, which takes one custom property (itemId), looks as follows:
110
```objective-c
111
[PrimedTracker.sharedInstance trackCustomEvent:@"VIDEOSTART" customProperties:@{@"itemId":@"32"}];
112 113
```

114
```objective-c
115
-(void)trackCustomEvent:(NSString *)eventType customProperties:(NSDictionary<NSString*,id> *)data;
116 117 118 119

```

# Usage Primed calls
120
## Initialisation
121
```objective-c
Bosko Petreski's avatar
Bosko Petreski committed
122
[Primed.sharedInstance initWithPublicKey:@"somekey" secretKey:@"somesecretkeywithalotofchars" connectionString:@"API_URL_GO_HERE"]
123 124
```

125
## Convert (ASYNC):
126 127
Upon successful personalisation, a list of results will be returned. Each result will contain a variable payload: the idea here is that PrimedIO is generic and supports freeform `Targets`, which can be item ID's (usually used in lookups after the personalise call), URL's, Boolean values, and any combination of these. Additionally, each result will contain a unique RUUID (Result UUID), randomly generated for this particular call and `Target`. It is used to track the conversion of this particular outcome, which is used to identify which of the A/B variants performed best. Conversion is also generic, but generally we can associate this with clicking a particular outcome. In order for PrimedIO to register this feedback, another call needs to be made upon conversion. This in turn allows the system to evaluate the performance (as CTR) of the underlying Model (or blend).

128
```objective-c
Bosko Petreski's avatar
Bosko Petreski committed
129
[Primed.sharedInstance convert:@"RUUID_GO_HERE"];
130 131 132 133
    
NSDictionary *dictData = @{@"device": @"iphone",
                            @"userid": @"someuserid"
                        };
Bosko Petreski's avatar
Bosko Petreski committed
134
[Primed.sharedInstance convert:@"RUUID_GO_HERE" data:dictData];
135 136
```

137 138 139 140 141
| arg | type | required | description | example |
| --- | ---- | -------- | ------ | ------- |
| ruuid | NSString | Yes | ruuid for which to register conversion | `"6d2e36d1-1b58-4fbc-bea8-868e3ec11c87"` |
| data | NSDictionary<NSString \*, NSObject \*> | No | freeform data payload | `{ heartbeat: 0.1 }` |

142
## Personalise (ASYNC):
143 144
This call obtains predictions for a given campaign and calls the callback function with the result. Personalisation requires at least a campaign key (NB, this is not the campaign name), e.g. `frontpage.recommendations`. 

145
```objective-c
146 147 148 149
NSDictionary *dictSignals = @{@"device": @"iphone",
                             @"userid": @"someuserid"
                            };
    
Bosko Petreski's avatar
Bosko Petreski committed
150
[Primed.sharedInstance personalise:@"frontpage.article.bottom" signals:dictSignals limit:3 success:^(NSDictionary *response) {    
151 152 153 154 155 156 157 158
    //Handle response
    NSLog(@"personalise: %@",response);
} failed:^(NSString *message) {
    //Handle message
    NSLog(@"personalise error: %@",message);
}];
```

159 160 161 162 163
| arg | type | required | description | example |
| --- | ---- | -------- | ------ | ------- |
| campaign | NSString | Yes | campaign key for which personalisation is retrieved | `frontpage.recommendations` |
| signals | NSDictionary<NSString \*, NSString \*> | No (defaults to `{}`) | key, value pairs of signals (itemId currently being viewed, deviceId, location, etc.) | `{itemId: '1234', userId: 'xyz'}` |
| limit | NSInteger | No (defaults to `5`) | number of desired results | `10` |
164
| abvariantLabel | NSString | No (defaults to `WRANDOM` assignment) | specify A/B variant for which to retrieve personalisation | `__CONTROL__` |
165 166
| success:\^(NSDictionary *response) | *callback function* | Yes | called when results returned succesfully |  |
| failed:\^(NSString *message) | *callback function* | Yes | called in case of failure |  |
167 168


169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
EXAMPLE RETURN VALUE:
```
{
	"campaign": {
        "key": "dummy.frontpage.recommendations"
    },
    "experiment": {
        "name": "myfirstexperiment",
        "salt": "sadfasdf",
        "abmembership_strategy": "WRANDOM",
        "abselectors": [],
        "matched_abselector": {
            "null": "IU8LOR2JL5LS3ZVN"
        },
        "abvariant": {
            "label": "A",
            "dithering": false,
            "recency": false
        }
    },
	"query_latency_ms": 42.66,
    "guuid": "554fe95a-214e-4d82-921a-e202eacf373b",
	'results': [
		{
			"target": {
                "uid": "50371aafd2f545809732877dc0cfb86e",
                "key": "8ba254d9-78d4-4b11-9e04-692bacda9c56",
                "value": {
                    "title": "2",
                    "url": "http://fields.com/2"
                }
            },
            "fscore": 0.7789,
            "components": [
                {
                    "model_uid": "b8071e37fe8547a5825d10ab17a05932",
                    "weight": 0.4,
                    "signal_uid": "d4358441be124902bb60972a6c555f80",
                    "cscore": 0.8150115180517363
                },
                {
                    "model_uid": "dc883e27a5a44e3ab7027f3619b3d726",
                    "weight": 0.6,
                    "signal_uid": "0d3afe0bc4b84200a403ad0edf9ffcc7",
                    "cscore": 0.7547711855338738
                }
            ],
            "recency_factor": 1.0,
            "ruuid": "ec12da8c-a045-4dfb-8618-d9d4f424ce24"

		}
	]
}
```