👋 Hello and welcome to HiggsMart! This sample iOS application will provide you with a hands-on way to understand how mParticle collects and forwards data, so you can easily implement data collection in your own projects. Throughout this application, the mParticle Apple and Media SDK have been set up to capture user events and identities and forward them to mParticle.
By using this sample app, you will quickly learn how to:
-
Collect and forward data with mParticle
-
View incoming data events and debugging information in real time
-
Implement data collection with mParticle's SDKs
-
Open
HiggsShopSampleApp.xcodeprojin Xcode -
Dependencies will automatically be updated by Swift Package Manager
-
In the
HiggsShopSampleAppscheme, update theMPARTICLE_KEYandMPARTICLE_SECRETenvironment variables fromREPLACEMEto your mParticle iOS API Key and secret.
- If you do not have an iOS API key, visit your mParticle Workspace to generate API Credentials under "Getting Started"
- Run the project using the
Command-R
This will spawn a simulator and open the Higgs Shop Sample App.
To make things simple yet declarative, this application has been built in such a way to keep event tracking close to the components that might logically trigger them rather than a fully DRY implementation. We've opted to be more repetitive so examples are consise and documented as necessary.
Please feel free to also visit our Doc Site to gain more familiarity with some of the more advanced features of mParticle.
In cases where it is necessary to track visitors as they navigate your iOS Application, mParticle offers Screen Tracking.
In this Sample App, screen views each fire a single Screen View when the component is rendered.
For example
// Renders an initial cart view when the screen loads
MParticle.sharedInstance().logScreen("View My Cart", eventInfo: ["number_of_products": numberOfProducts, "total_product_amounts": subTotal])In some cases, we fire a Commerce Event instead of a Screen View to track more e-Commerce related attributes.
Most often, you will need to use Custom Events to track events in a way that is unique to your use case. mParticle provides types of Custom Events ranging from Navigation Events to Social Media Engagement and are mostly used to organize your data in a way that makes sense to you.
Many of our views make use of these events, for example, in the LandingViewController Component.
// Logs an event to signify that the user clicked on a button
if let event = MPEvent(name: "Landing Button Click", type: .other) {
MParticle.sharedInstance().logEvent(event)
}This Sample App emulates a simple e-Commerce application and makes heavy use of mParticle's Commerce Events.
Some events used in this application:
- Add To Cart
- Remove From Cart
- Product Detail
- Product Impression
- Checkout
- Purchase
Most Commerce Events follow a similar pattern, requiring that you first generate an mParticle Product Object, which then gets passed into the MPCommerceEvent object.
You should map your own product attributes to be consistent with your Data Plan if you are leveraging that feature. Using Data Plans ensures data consistency within an app and across devices.
let mpProduct = MPProduct(name: name, sku: sku, quantity: quantity, price: price)
mpProduct.setUserDefinedAttributes(productAttributes)
let event = MPCommerceEvent.init(action: .addToCart, product: mpProduct)
MParticle.sharedInstance().logEvent(event)Most Commerce Events are used within the following components:
/HiggsShopSampleApp/ProductDetailViewController.swift/HiggsShopSampleApp/CartViewController.swift/HiggsShopSampleApp/CheckoutViewController.swift
As a developer, sometimes the best way to learn is to just dig into the code or your debugging tools. To that end, this sample app ships verbose logging turned on, so that you can view details of what our SDK is doing within Xcode's console.
mParticle simplifies the process of collecting customer data events from your apps, and forwarding this data to a wide variety of downstream systems for analytics, data processing, and marketing. To illustrate this process, here is an example of a data connection using HiggsMart as an input, and a sample output.
Note: In this example, we will be using Webhook.site to simulate data transferring between the HiggsMart and your own services. Webhook.site is not an mParticle service and is only being used as to simulate an end-to-end full data flow to a third party system.
By generating your Apple API key and adding it to this project, you have already set up HiggsMart as a Apple input input. This means that your on-site behaviors in the local build of this app will be captured and sent to mParticle as data events.
To see these data events coming in to mParticle real time, view the mParticle Live Stream by navigating to Data Master > Live Stream in the mParticle UI.
Among other things, Live Stream allows you to:
-
Review incoming data to ensure correct SDK and/or server-to-server implementation
-
Quickly identify and debug data collection errors
-
Review outbound events to your connected integrations
-
Test that your integrations are set up correctly
Outputs are destinations for data that you have collected with mParticle. These include 250+ integrations with leading platforms for analytics (like Indicative or Mixpanel), data processing services (like Amazon Kinesis), or marketing tools (like Braze or Appsflyer).
An output can also be a simple Webhook, however, and since this provides an easy way to set up a complete flow of data, a Webhook is what we'll use for this example. To set up a Webhook output in mParticle:
-
Navigate to Setup > Inputs in the left column of your mParticle Workspace.
-
Click the "Add Event Output" button in the top-right corner of the UI.
-
Select "Webhooks" from the dropdown.
-
Enter the configuration name “Apple Sample App”
-
Open Webhook.site in a new browser tab and copy your Webhook's unique URL.
-
In mParticle, paste the unique URL in the "POST URL" field in the event configuration window, then click "Save."
A connection is the combination of an input, an output, and the configuration information that determines how data should be shared between the two. To create a connection between HiggsMart and your Webhook:
-
Navigate to Connections > Connect in the left column of your mParticle Workspace.
-
Click "Apple Platform" to select the apple app input you just created.
-
Click "Connect Output" to view all available outputs.
-
Select the Webhooks group of connections, then click "Select Configuration."
-
Choose "Apple Sample App" from the dropdown, then click "Next."
-
Toggle the “Status” button to “Active,” then click “Add Connection” to create the connection.
At this point, data should be flowing from your sample app, to mParticle, then finally out to your Webhook output. Let's test this to make sure it's working. Back in the Data Master > Live Stream view:
-
Click the "Message Direction" dropdown and select “Outbound.”
-
Go back to Webhook.site to view your request details
Here, you should see your events from mParticle arriving at their intended destination. And that's it! You have successfully collected and forwarded data with mParticle.
This project uses SnapKit to simplify AutoLayout constraints.
We also use SwiftLint to format code automatically using swiftlint --fix.
Linting will be run as a build phase during Xcode builds if SwiftLint is installed. It's not required to have swiftlint installed for testing the Sample Apps, but you can install it if desired by running brew install swiftlint.
This can be helpful if you want to submit a Pull Request so you are aware of any potential lint issues before they are flagged by CI.
The mParticle Apple SDK is available under the Apache License, Version 2.0. See the LICENSE file for more info.