xambarr / mapbox-events-ios

Mapbox Events Framework for iOS

🎟 Mapbox Mobile Events

The Mapbox Mobile Events SDK collects anonymous data about the map and device location to continuously update and improve your maps.

📦 Client Frameworks

• Mapbox Maps SDK
• Mapbox Navigation SDK
• Mapbox Vision SDK
• Mapbox ReactNative SDK

🏎 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:

MMEEventsManager *manager = [MMEventsManager.sharedManager 
    initializeWithAccessToken:@"your-mapbox-token" 
    userAgentBase:@"user-agent-string"
    hostSDKVersion:@"1.0.0"];
[manager sendTurnstileEvent];

Or, in 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.

The use of Mapbox SDKs and APIs on mobile devices are governed by our
Terms of Service 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.

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:

- (void)eventsManager:(MMEEventsManager *)eventsManager 
    didEncounterError:(NSError *)error;

to be informed of any NSErrors or NSExceptions the framework encounters. NSExceptions 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:

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, 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.