PeachCollector for iOS
The Peach Collector framework for iOS provides simple functionalities to facilitate the collect of events.
PeachCollector helps you by managing a queue of events serialized until they are successfully published.
The library is suitable for applications running on iOS 12 and above or tvOS 12 and above. The project is meant to be opened with the latest Xcode version (currently Xcode 12).
Install via Carthage
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update $ brew install carthage
To integrate PeachCollector into your Xcode project using Carthage, specify it in your
carthage update to build the framework and drag the built
PeachCollector.framework into your Xcode project.
Install via Swift Package Manager
SPM integration is available since version 1.2.0
- In XCode menu, click on
Add Package Dependency...
- Enter the project url:
https://github.com/ebu/peach-collector-ios.gitand click on the
- Select the
masterbranch and click on the
- Click on the
When you want to use classes or functions provided by the library in your code, you must import it from your source files first.
Import the global header file in your
Initializing the collector
PeachCollector is automatically initialized at the launch of the app. You just need a
PeachCollectorPublisher to start sending the queued events.
You can either provide a SiteKey or a full URL address in order to configure the publisher.
PeachCollectorPublisher *publisher = [[PeachCollectorPublisher alloc] initWithSiteKey:@"zzebu00000000017"]; [PeachCollector setPublisher:publisher withUniqueName:@"My Publisher"];
let publisher = PeachCollectorPublisher.init(siteKey: "zzebu00000000017") PeachCollector.setPublisher(publisher, withUniqueName: "My Publisher")
Configuring the collector
- A user ID can be defined using the
- If userIDs are generated automatically for anonymous user. You can use the
userIsLoggedInflag to define if the user is logged in or not
- For debugging purpose, a
isUnitTestingflag is available. If true, notifications will be sent by the collector (see
- The collector retrieves the identifierForVendor to set as the device ID in order to track users that do not have user IDs. People can choose to limit tracking on their devices and this ID will not be sent to Peach. In this case, if there is no
userIDdefined, no events will be recorder or sent. Unless you set the
shouldCollectAnonymousEventsflag to true. Default is false.
- Optionally, you can define an
implementationVersionby setting a PeachCollector property.
maximumStorageDaysis the maximum number of days an event should be kept in the queue (if it could not be sent).
maximumStoredEventsis the maximum number of events that should be kept in the queue.
appIDcan be defined if you don't want to use the default value (which is the bundle ID of the app).
PeachCollector.userID = @"123e4567-e89b-12d3-a456-426655440000"; PeachCollector.appID = @"test.app.id"; [PeachCollector sharedCollector].isUnitTesting = YES; [PeachCollector sharedCollector].shouldCollectAnonymousEvents = YES; PeachCollector.implementationVersion = @"1"; PeachCollector.maximumStorageDays = 5; PeachCollector.maximumStoredEvents = 1000;
PeachCollector.userID = "123e4567-e89b-12d3-a456-426655440000"; PeachCollector.appID = "test.app.id"; PeachCollector.shared.isUnitTesting = true; PeachCollector.shared.shouldCollectAnonymousEvents = true; PeachCollector.implementationVersion = "1";
Configuring a Publisher
A publisher needs to be initialized with a SiteKey or a full URL address as seen previously. But it has 4 others properties that are worth mentioning :
interval: The interval in seconds at which events are sent to the server (interval starts after the first event is queued). Default is 20 seconds.
maxEventsPerBatch: Number of events queued that triggers the publishing process even if the desired interval hasn't been reached. Default is 20 events.
maxEventsPerBatchAfterOfflineSession: Maximum number of events that can be sent in a single batch. Especially useful after a long offline session. Default is 1000 events.
gotBackPolicy: How the publisher should behave after an offline period. Available options are
SendAll (sends requests with
SendBatchesRandomly (separates requests by a random delay between 0 and 60 seconds).
Flushing and Cleaning
Flush is called when the application is about to go to background, or if a special type of event is sent while in background (events that will potentially push the application into an inactive state). It will try to send all the queued events (even if the maximum number of events hasn't been reached)
Clean will simply remove all current queued events. It is never called in the life cycle of the framework.
Clean can be called manually.
[PeachCollector flush]; [PeachCollector clean];
Special type of events
Some events can be queued when the app is in background but still active. For example, when playing an audio media and controlling the playback directly on the device's lock screen. Some of those events that can occur during a playback will trigger a flush of all queued events. This mechanism is implemented to make sure events are published before the app becomes totally inactive.
For now, events that trigger this flush are
You can add another type of event to this list:
Recording an Event
// recommendation hit event [PeachCollectorEvent sendRecommendationHitWithID:@"reco01" itemID:@"media01" hitIndex:1 appSectionID:@"news/videos" source:nil component:nil]; // media play event PeachCollectorContextComponent * component = [PeachCollectorContextComponent new]; component.type = @"player"; component.name = @"AudioPlayer"; component.version = @"1.0"; PeachCollectorContext audioContext = [[PeachCollectorContext alloc] initMediaContextWithID:@"reco01" component:component appSectionID:nil source:@"nil]; PeachCollectorProperties audioProperties = [PeachCollectorProperties new]; audioProperties.audioMode = PCMediaAudioModeNormal; audioProperties.startMode = PCMediaStartModeNormal; audioProperties.playbackPosition = @(0.0) [PeachCollectorEvent sendMediaPauseWithID:@"media01" properties:audioProperties context:audioContext metadata:audioMetadata];
PeachCollectorEvent.sendRecommendationHit(withID: "reco00", itemID: "media01", hit: 1, appSectionID: "news/videos", source: nil, component: nil) let component = PeachCollectorContextComponent.init() component.type = "player" component.name = "AudioPlayer" component.version = "1.0" let audioContext = PeachCollectorContext.init(mediaContextWithID: "reco00", component: component, appSectionID: "Demo/AudioPlayer", source: "Demo.reco") let audioProperties = PeachCollectorProperties.init() audioProperties.audioMode = .normal PeachCollectorEvent.sendMediaPlay(withID: "media01", properties: audioProperties, context: audioContext, metadata: audioMetadata)
Setting up a player tracker
To track a player automatically, you just need to provide the AVPlayer instance and information about the item that is being played.
You can provide information about the item or leave empty. The tracker will only update (or create if not provided) the
props part of the events with data from the player
You can also stop tracking an item manually.
[PeachPlayerTracker setPlayer:self.videoPlayer]; [PeachPlayerTracker trackItemWithID:@"video0001" context:nil props:nil metadata:nil]; [PeachPlayerTracker clearCurrentItem];
PeachPlayerTracker.setPlayer(videoPlayer) PeachPlayerTracker.trackItem(withID:"video0001", context:nil, props:nil, metadata:nil) PeachPlayerTracker.clearCurrentItem()
To see examples of how the framework works, two demo projects (in Objective-C and Swift) are available in the Xcode project.
App privacy details on the App Store
Starting December 8, 2020, app developers are required to provide information about their Privacy Practices when submitting apps or updated apps to the App Store. Privacy Practices are displayed to app users in a concise nutrition label format on the app page in the app store.
The following is based on the data automatically collected by PeachCollector, not the data you choose to send in any event or any data you retrieve directly from the app (authentication or other analytics).
Data types collected
|Health and fitness||NO|
|Identifiers||NO but...||Developers can manually input a User ID that will be sent in all the events collected. This user ID is not generated by the collector. Also, the collector does not make use of the IDFA.|
|Usage data||YES||Product interactions are defined and sent by the developers (Page views, Recommendation hits, Media plays...)|
|Other data||YES||PeachCollector retrieves and sends technical device information (OS, device type, language...). It also uses the IDFV (Identifier for Vendor)|
Data use purposes
Data collected will be used for Analytics at first and then for Product personalization (when recommendations generated by PEACH will be displayed in the app)
Data linked to an identity
Data types collected through PeachCollector are usualy connected to an identifier like device ID (when available), or other identifiers like user IDs when configured by developers.
Therefore, app developers should select Yes when asked if the data is linked to an identity.