https://github.com/mapbox/mapbox-events-ios
Mapbox Events Framework for iOS
https://github.com/mapbox/mapbox-events-ios
Last synced: 6 months ago
JSON representation
Mapbox Events Framework for iOS
- Host: GitHub
- URL: https://github.com/mapbox/mapbox-events-ios
- Owner: mapbox
- License: other
- Created: 2016-12-09T21:59:14.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-09-18T12:50:09.000Z (9 months ago)
- Last Synced: 2024-11-28T13:17:45.900Z (6 months ago)
- Language: Objective-C
- Homepage:
- Size: 34.7 MB
- Stars: 20
- Watchers: 111
- Forks: 38
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 🎟 Mapbox Mobile Events
[](https://www.bitrise.io/app/63d52d847cdb36db)
The Mapbox Mobile Events SDK collects [anonymous data](https://www.mapbox.com/telemetry/) about
the map and device location to continuously update and improve your maps.
### 📦 Client Frameworks
- [Mapbox Maps SDK](https://github.com/mapbox/mapbox-gl-native/)
- [Mapbox Navigation SDK](https://github.com/mapbox/mapbox-navigation-ios/)
- [Mapbox Vision SDK](https://github.com/mapbox/mapbox-vision-ios)
- [Mapbox ReactNative SDK](https://github.com/mapbox/react-native-mapbox-gl)
### 🏎 Quick Start
If you are using another Mapbox SDK, you should not need to do any special setup to use Mapbox Mobile Events.
If you are integrating Mapbox Mobile Events into an application which does not use another Mapbox SDK you
will need to include `MapboxMobileEvents.framework` in your application, and in the application delegate's
`…didFinishLaunching…` method, add:
```objc
MMEEventsManager *manager = [MMEventsManager.sharedManager
initializeWithAccessToken:@"your-mapbox-token"
userAgentBase:@"user-agent-string"
hostSDKVersion:@"1.0.0"];
[manager sendTurnstileEvent];
```
Or, in Swift:
```swift
let eventsManager = MMEEventsManager.sharedManager().initialize(
withAccessToken: "your-mapbox-token",
userAgentBase: "user-agent-string",
hostSDKVersion: "1.0.0")
eventsManager.sendTurnstileEvent()
```
### 🎟 Sending Events
The preferred API for creating and sending an events uses the private method `-MMEEventManager pushEvent:`
if you think your application needs to send events please contact your Technical Account Manager or open an issue
in this repository with details.
### 💣 Debugging
Usually when running the Mobile Events SDK in the Emulator it does not send events or emit debug
messages, you can enable these by setting keys in the `Info.plist` of your application:
```
MMEDebugLogging: YES
MMECollectionEnabledInSimulator: YES
```
### 🗺 Foreground and Background Location Collection
The MapboxMobileEvents frameworks collect location data to help us improve the map. We strive to maintain a
low power and network usage profile for this collection and take great care to anonymize all data in accordance
with our [privacy policy](https://www.mapbox.com/legal/privacy).
The use of Mapbox SDKs and APIs on mobile devices are governed by our
[Terms of Service](https://www.mapbox.com/legal/tos#[MomMom]) which requires your app not interfere with
or limit the data that the Mapbox SDK sends to us, whether by modifying the SDK or by other means. If your
application requires different terms, please contact [Mapbox Sales](https://www.mapbox.com/contact/sales/).
#### Background Location in iOS 13
If your application enables background location, the MapboxMobileEvents framework collects telemetry in the
background using a passive method which allows for very low power usage. If your application does not use
background location, make sure that the permissions keys for it are removed in the
`Info.plist`: `NSLocationAlwaysAndWhenInUseUsageDescription`,
`NSLocationAlwaysUsageDescription`, as well as the `UIBackgroundMode` `location`.
### ⚠️ Error and Exception Handling and Reporting
The MapboxMobileEvents frameworks strives to contain all internal exceptions and errors in an effort to prevent
errors from directly impacting the end users of applications which use the framework. The framework will attempt
to report them to our backend, in a redacted form, for analysis by Mapbox.
Applications and frameworks which embed `MapboxMobileEvents.framework` can implement the
`MMEEventsManagerDelegate` method after setting `MMEEVentsManager.sharedManager.delegate`:
```objc
- (void)eventsManager:(MMEEventsManager *)eventsManager
didEncounterError:(NSError *)error;
```
to be informed of any `NSError`s or `NSException`s the framework encounters. `NSException`s are reported
wrapped in an `NSError` with the error code `MMEErrorException` and the exception included in the user info
dictionary under the key `MMEErrorUnderlyingExceptionKey`.
If a framework wishes to report errors via the mobile events API two convenience methods are provided
on `MMEEventsManager`:
```objc
NSError *reportableError = nil;
// make a call with an **error paramater
[MMEEventsManager.sharedManager reportError:reportableError];
@try {
// do something dangerous
}
@catch (NSException *exceptional) {
[MMEEventsManager.sharedManager reportException:exceptional];
}
```
### 🧪 Testing
Some legacy test cases are written using [Cedar](https://github.com/cedarbdd/cedar), to run the test in `Xcode` using
`Command-U` you'll need to unzip the framework located in the `Carthage/Build/iOS/` to run these tests.