{"id":27954460,"url":"https://github.com/ebu/peach-collector-ios","last_synced_at":"2025-05-07T17:29:48.337Z","repository":{"id":52649874,"uuid":"220946751","full_name":"ebu/peach-collector-ios","owner":"ebu","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-07T21:10:07.000Z","size":353,"stargazers_count":2,"open_issues_count":2,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-13T22:26:55.046Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-11-11T09:35:44.000Z","updated_at":"2023-06-22T12:52:13.000Z","dependencies_parsed_at":"2023-10-23T09:37:41.571Z","dependency_job_id":null,"html_url":"https://github.com/ebu/peach-collector-ios","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fpeach-collector-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fpeach-collector-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fpeach-collector-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebu%2Fpeach-collector-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebu","download_url":"https://codeload.github.com/ebu/peach-collector-ios/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252926290,"owners_count":21826284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T17:29:47.639Z","updated_at":"2025-05-07T17:29:48.315Z","avatar_url":"https://github.com/ebu.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Swift Package Manager compatible](https://img.shields.io/badge/SPM-compatible-4BC51D.svg?style=flat)](https://swift.org/package-manager/)\n\n# About\n\nThe **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.\n\n# Compatibility\n\nThe 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).\n\n# Installation\n\n## Install via Carthage\n\n[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.\n\nYou can install Carthage with [Homebrew](http://brew.sh/) using the following command:\n\n```bash\n$ brew update\n$ brew install carthage\n```\n\nTo integrate PeachCollector into your Xcode project using Carthage, specify it in your `Cartfile`:\n\n```ogdl\ngithub \"ebu/peach-collector-ios\"\n```\n\nRun `carthage update` to build the framework and drag the built `PeachCollector.framework` into your Xcode project.\n\n## Install via Swift Package Manager\n\nSPM integration is available since version 1.2.0\n\n- In XCode menu, click on `File` \u003e `Swift Packages` \u003e `Add Package Dependency...`\n- Enter the project url: `https://github.com/ebu/peach-collector-ios.git` and click on the `Next` button.\n- Select the `master` branch and click on the `Next` button.\n- Click on the `Finish` button.\n\n\n# Usage\n\nWhen you want to use classes or functions provided by the library in your code, you must import it from your source files first.\n\n## Framework integration\nImport the global header file in your `AppDelegate` using:\n#### Objective-C\n```objectivec\n@import PeachCollector;\n```\n#### Swift\n```swift\nimport PeachCollector\n```\n\n\n## Initializing the collector\n`PeachCollector` is automatically initialized at the launch of the app. You just need a `PeachCollectorPublisher` to start sending the queued events.\nYou can either provide a __SiteKey__ or a full __URL address__ in order to configure the publisher.\n\n\n#### Objective-C\n```objectivec\nPeachCollectorPublisher *publisher = [[PeachCollectorPublisher alloc] initWithSiteKey:@\"zzebu00000000017\"];\n[PeachCollector setPublisher:publisher withUniqueName:@\"My Publisher\"];\n```\n#### Swift\n```swift\nlet publisher = PeachCollectorPublisher.init(siteKey: \"zzebu00000000017\")\nPeachCollector.setPublisher(publisher, withUniqueName: \"My Publisher\")\n```\n\n## Configuring the collector\n\n- A device ID can be defined using the **`deviceID`** PeachCollector property. If set, it will override the default value (vendor ID)\n- A user ID can be defined using the **`userID`** PeachCollector property.\n- If userIDs are generated automatically for anonymous user. You can use the `userIsLoggedIn` flag to define if the user is logged in or not\n- For debugging purpose, a **`isUnitTesting`** flag is available. If true, notifications will be sent by the collector (see `PeachColletorNotifications.h`)\n- 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 **`userID`** defined, no events will be recorder or sent. Unless you set the **`shouldCollectAnonymousEvents`** flag to *true*. Default is *false*.\n- Optionally, you can define an **`implementationVersion`** by setting a PeachCollector property.\n- **`maximumStorageDays`** is the maximum number of days an event should be kept in the queue (if it could not be sent).\n- **`maximumStoredEvents`** is the maximum number of events that should be kept in the queue. \n- An **`appID`** can be defined if you don't want to use the default value (which is the bundle ID of the app).\n\n#### Objective-C\n```objectivec\nPeachCollector.userID = @\"123e4567-e89b-12d3-a456-426655440000\";\nPeachCollector.appID = @\"test.app.id\";\n[PeachCollector sharedCollector].isUnitTesting = YES;\n[PeachCollector sharedCollector].shouldCollectAnonymousEvents = YES;\nPeachCollector.implementationVersion = @\"1\";\nPeachCollector.maximumStorageDays = 5;\nPeachCollector.maximumStoredEvents = 1000;\n```\n\n#### Swift\n```swift\nPeachCollector.userID = \"123e4567-e89b-12d3-a456-426655440000\";\nPeachCollector.appID = \"test.app.id\";\nPeachCollector.shared.isUnitTesting = true;\nPeachCollector.shared.shouldCollectAnonymousEvents = true;\nPeachCollector.implementationVersion = \"1\";\n\n```\n\n### Configuring a Publisher\nA publisher needs to be initialized with a __SiteKey__ or a full __URL address__ as seen previously.\nBut it has 4 others properties that are worth mentioning :\n\n**`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.\n\n**`maxEventsPerBatch`**: Number of events queued that triggers the publishing process even if the desired interval hasn't been reached. Default is 20 events.\n\n**`maxEventsPerBatchAfterOfflineSession`**: Maximum number of events that can be sent in a single batch. Especially useful after a long offline session. Default is 1000 events.\n\n**`gotBackPolicy`**: How the publisher should behave after an offline period. Available options are `SendAll` (sends requests with **`maxEventsPerBatchAfterOfflineSession`** continuously), `SendBatchesRandomly` (separates requests by a random delay between 0 and 60 seconds).\n\n### Adding custom data to a Publisher's client information\nEverytime events are sent to the defined sitekey or server, the payload (containing the JSON description of the events) has a single description of the client used. You can add any custom fields to this client description and it will be sent in every request.\n#### Objective-C\n```objectivec\n[publisher addCustomClientString:@\"France\" forKey:@\"country\"];\n[publisher addCustomClientNumber:@(YES) forKey:@\"is_geolocalized\"];\n```\n#### Swift\n```swift\npublisher.addCustomClientString(\"France\", forKey: \"country\")\npublisher.addCustomClientNumber(true, forKey: \"is_geolocalized\")\n```\nFunctions are also available to retrieve a custom field value and remove a custom field.\n\n\n## Setting up a remote configuration\n`PeachCollector` allows you to set up a remote configuration URL. Remote configurations are simple JSON files with different fields to configure the publisher. For that, you need to provide the URL at the initialisation stage of the publisher.\n\n#### Objective-C\n```objectivec\nPeachCollectorPublisher *publisher = [[PeachCollectorPublisher alloc] initWithSiteKey:@\"zzebu00000000017\" remoteConfiguration:@\"https://peach-static.ebu.io/zzebu/config_example.json\"];\n[PeachCollector setPublisher:publisher withUniqueName:@\"My Publisher\"];\n```\n#### Swift\n```swift\nlet publisher = PeachCollectorPublisher.init(siteKey: \"zzebu00000000017\", remoteConfiguration: \"https://peach-static.ebu.io/zzebu/config_example.json\")\nPeachCollector.setPublisher(publisher, withUniqueName: \"My Publisher\")\n```\nIn this remote configuration, you can for example define the interval (at which events are sent), the batch size (number of events per request) or the type of events that should be sent by the publisher.\n\n### Flushing and Cleaning\n\n**`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)\n\n**`Clean`** will simply remove all current queued events. It is never called in the life cycle of the framework.\n\n`Flush` and `Clean` can be called manually.\n\n#### Objective-C\n```objectivec\n[PeachCollector flush];\n[PeachCollector clean];\n```\n#### Swift\n```swift\nPeachCollector.flush();\nPeachCollector.clean()\n```\n\n## Special type of events\nSome 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.\n\nFor now, events that trigger this flush are `media_pause` and `media_stop` events.\nYou can add another type of event to this list:\n#### Objective-C\n```objectivec\n[PeachCollector addFlushableEventType:@\"media_error\"]\n```\n#### Swift\n```swift\nPeachCollector.addFlushableEventType(\"media_error\")\n```\n\n### Recording an Event\n\n#### Objective-C\n```objectivec\n[PeachCollectorEvent sendRecommendationHitWithID:@\"reco01\"\n\t\t\t\t\t  itemID:@\"media01\"\n                                        hitIndex:1\n                                    appSectionID:@\"news/videos\"\n                                          source:nil\n                                       component:nil];\n```\n#### Swift\n```swift\nPeachCollectorEvent.sendRecommendationHit(withID: \"reco00\",\n\t\t\t\t\t  itemID: \"media01\",\n\t\t\t\t\t     hit: 1,\n\t\t\t\t    appSectionID: \"news/videos\",\n\t\t\t\t\t  source: nil,\n\t\t\t\t       component: nil)\n```\n\n### Setting up a player tracker\n\nTo track a player automatically, you just need to provide the AVPlayer instance and information about the item that is being played.\nYou 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\nYou can also stop tracking an item manually.\n\n#### Objective-C\n```objectivec\n[PeachPlayerTracker setPlayer:self.videoPlayer];\n[PeachPlayerTracker trackItemWithID:@\"video0001\"\n                            context:nil\n                              props:nil\n                           metadata:nil];\n[PeachPlayerTracker clearCurrentItem];                           \n```\n#### Swift\n```swift\nPeachPlayerTracker.setPlayer(videoPlayer)\nPeachPlayerTracker.trackItem(withID:\"video0001\", context:nil, props:nil, metadata:nil)\nPeachPlayerTracker.clearCurrentItem()\n```\n\n\n\n\n## Demo projects\n\nTo see examples of how the framework works, two demo projects (in Objective-C and Swift) for iOS and one demo for tvOS are available in the Xcode project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Fpeach-collector-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febu%2Fpeach-collector-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febu%2Fpeach-collector-ios/lists"}