Analytics Swift Amplitude Plugin


Amplitude is an event tracking and segmentation platform for your web and mobile apps. By analyzing the actions your users perform, you can gain a better understanding to drive retention, engagement, and conversion.

Getting started

  1. Before you start, go to your Amplitude workspace. Click Settings in the bottom left, then click Projects in the left menu. Select your Project. Copy the Amplitude API Key and Secret Key for the project.
  2. From the Segment web app, click Catalog, then click Destinations.
  3. Find the Destinations Actions item in the left navigation, and click it.
  4. Click the “Amplitude” item to select it and click Configure.
  5. Choose which of your sources to connect the destination to. (You can connect more sources to the destination later.)

Once you have a mapping, you can follow the steps in the Destinations Actions documentation on Customizing mappings.

The Amplitude Swift plugin doesn’t send events to Amplitude from the client side. It instead adds Amplitude session data and then sends it server side from the Amplitude Actions destination.

Adding the dependency

through Xcode

In the Xcode File menu, click Add Packages. You’ll see a dialog where you can search for Swift packages. In the search field, enter the URL to this repository.

https://github.com/segment-integrations/analytics-swift-amplitude{:target=”_blank”}

You’ll then have the option to pin to a version, or specific branch, as well as which project in your workspace to add it to. Once you’ve made your selections, click the Add Package button.

through Package.swift

Open your Package.swift file and add the following do your the dependencies section:

.package(
            name: "Segment",
            url: "https://github.com/segment-integrations/analytics-swift-amplitude.git",
            from: "1.1.3"
        ),

Using the Plugin in your App

Open the file where you setup and configure the Analytics-Swift library. Add this plugin to the list of imports.

import Segment
import SegmentAmplitude // <-- Add this line

Just under your Analytics-Swift library setup, call analytics.add(plugin: ...) to add an instance of the plugin to the Analytics timeline.

let analytics = Analytics(configuration: Configuration(writeKey: "<YOUR WRITE KEY>")
                    .flushAt(3)
                    .trackApplicationLifecycleEvents(true))
analytics.add(plugin: AmplitudeSession())

Your events receive session data and start flowing to Amplitude in Cloud Mode.

Native Amplitude events

Newer versions of the Swift Amplitude Plugin (V 1.4.1 and up) will send the native Amplitude Session Start and Session End events in addition to tracking session_id. These versions of the plugin also support sending native Amplitude lifecycle events in lieu of the Segment lifecycle events to Amplitude. These will appear in your Amplitude dashboard with the [Amplitude] prefix but will not be sent to Segment.

Log Purchases in existing destination instances

Initially, the Log Event Action was reporting purchases to Amplitude for all events containing a products array, even if the products were just added to cart. This inflated the LTV Chart in Amplitude.

To resolve this, purchase reporting takes place in a new Action called Log Purchase.

For instances created prior to before the Log Purchases action was released, you need to manually add the Log Purchases Action to report purchases to Amplitude.

To manually add the Log Purchases Action:

  1. Add a new Mapping for the Log Purchases Action. The default trigger for this action is Order Completed events.
  2. Modify the Trigger if you need to report purchases for any other events.
  3. Modify the Trigger of Log Event to exclude these same events. This helps you to avoid sending the same event twice.
  4. Enable the Log Purchases mapping.

Connection Modes for Amplitude (Actions) destination

The Amplitude (actions) destination does not offer a device-mode connection mode. If you’re using one of Segment’s new libraries (Analytics.js 2.0, Swift or Kotlin) with the Actions-framework version of the destination, you do not need the device-mode connection.

Most previous deployments of the Amplitude Segment destination used the device-mode connection to use the session_id tracking feature. The new Actions-framework Amplitude destination, includes session ID tracking by default. This means you don’t need to bundle any software to run on the user’s device, or write any code. It also means that you can use more of the Segment platform features on data going to Amplitude, such as Protocols filtering and transformations, and Profiles Identity Resolution.

Session tracking is available with Segment’s new libraries: Analytics.js 2.0, Swift or Kotlin

Device ID Mappings

The Amplitude destination requires that each event include either a Device ID or a User ID. If a User ID isn’t present, Amplitude uses the a Device ID, and vice versa, if a Device ID isn’t present, Amplitude uses the User ID.

By default, Segment maps the Segment property context.device.id to the Amplitude property Device ID. If context.device.id isn’t available, Segment maps the property anonymousId to the Amplitude Device ID. The Actions interface indicates this with the following contents of the Device ID field: coalesce( context.device.id anonymousId ).

Enable Amplitude session tracking

To enable session tracking in Amplitude when using the Segment Swift library:

  1. Enable trackApplicationLifecycleEvents in your configuration.
  2. Add the Amplitude Session plugin to your project.
  3. Initialize the plugin (example)
    analytics?.add(plugin: AmplitudeSession(name: "Amplitude"))
    

Important differences from the classic Amplitude destination

The classic Amplitude destination captures the following user fields in device-mode (when it runs on the user’s device):

  • Device Type (for example, Mac, PC, mobile device)
  • Platform (for example iOS or Android)

Amplitude (Actions) runs in cloud-mode, and does not capture these fields.

Available Actions

Build your own Mappings. Combine supported triggers with the following -supported actions:

Mapping limits per destination

Individual destination instances have support a maximum of 50 mappings.

Amplitude (Actions) uses Amplitude’s HTTP API v2

If you used Amplitude Classic in cloud-mode, you’ll notice different responses from Amplitude to calls you make with the destination. Classic Amplitude was built on Amplitude’s now-deprecated HTTP API v1.

You configure the Amplitude (Actions) destination through Filters and Actions. Consult the table below for information about configuring your Amplitude (Actions) destination similarly to your classic Amplitude destination.

Contact Segment support if you find features missing from the Amplitude (Actions) destination that were available in the classic Amplitude destination.

Amplitude settings mapping

amplitude Classic Destination Setting How to enable in amplitude (Actions)
Connection Settings
API Key
Cloud Device-web Device-mobile

Global Setting


Track Products Once
Device-web

Not applicable to Cloud mode

Version Name
Device-web

Action field App Version.


Defaults to context.app.version.

Connection Mode
Cloud Device-web Device-mobile

Actions support Cloud mode connections

Page and Screen
Track all pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


When enabled, Amplitude (Actions) tracks all Page calls by default

Track all Screens
Cloud Device-web Device-mobile

Subscription Page Calls


When enabled, Amplitude (Actions) tracks all Screen calls by default

Track Categorized Pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


Add a Trigger filter condition to check that Event Property category exists

Track Named Pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


Add a Trigger filter condition to check that Event Property name exists

Traits
Group Type Trait
Cloud Device-web Device-mobile

Subscription Group Identify User.


Select a value in the Group Type actions field. This field is mandatory in Amplitude (Actions). In the Amplitude Classic destination, ommiting a value for property field resulted in Amplitude creating a group called [Segment] Group.

Group Value Trait
Cloud Device-web Device-mobile

Subscription Group Identify User.


Select a value in the Group Value actions field. This field is mandatory in Amplitude actions. In the Amplitude Classic destination, ommiting a value for this property resulted in an alpha-numeric value.

Traits to Append
Cloud

Not supported with Actions

Traits to Increment
Cloud Device-web Device-mobile

Not supported with Actions

Traits to Prepend
Cloud

Not supported with Actions

Traits to Set Once
Cloud Device-web Device-mobile

Not supported with Actions

Other Settings
Append Fields to Event Properties
Device-web Device-mobile

Not supported with Actions

Batch Events
Device-web

Use Batch Endpoint field on the Log Event action


Enable Location Listening
Device-mobile

Use context.location.latitude and context.location.longitude on the mobile client. Other destinations may also process this data. Amplitude uses IP-based location, if you’re unable to send latitude and longitude.

Event Upload period millis
Device-web

Not configurable for Cloud-mode batching

Event Upload Threshold
Device-web

Not configurable for Cloud-mode batching

Force HTTPS
Device-web

Not configurable in Cloud-mode, https is enabled by default.

Map Query Params to Custom Property
Cloud Device-web

Not supported with Actions

Prefer Anonymous Device ID
Cloud Device-web Device-mobile

Actions field Device ID.


Replace the contents of the field with your preferred value.

Save Referrer, URL Params, GCLID Once per Session
Device-web

This setting supported an edge case that is not applicable to Amplitude (Actions)

Secret Key
Cloud Device-web Device-mobile

Global Setting


Enable Alias
Cloud

Use the Map User action.


The Map User action is not enabled by default. Add a new Subscription to access the Map User action.

Send to Batch Endpoint
Cloud

Use Batch Endpoint field on the Log Event action


Track GCLID
Device-web

Not supported with Actions

Track Referrer to Amplitude
Device-web

Update the User Properties mapping to send context.page.referrer.

Track Revenue per Product
Cloud Device-web Device-mobile

Actions field Track Revenue Per Product.


Available in any subscription that uses the Log Event action.
In Amplitude (Actions), this setting elevates revenue to a top-level property. This allows revenue data to pass through to Amplitude’s LTV reports.

Track Session Events to Amplitude
Device-web

This setting sends [Session Started] and [Session Ended] events. However, Session ID is used most often in session-based reporting. Analytics.js sources track Session ID by default. Mobile sources require a plugin to enable Session ID tracking. For more information, see Enable Session Tracking for Analytics.js 2.0

Track UTM Properties to Amplitude
Cloud Device-web

Supported by default. See the UTM Properties section to view the mappings.

Unset Params Referrer on New Session
Device-web

Not supported with Actions

Use Advertising ID for Device ID
Cloud Device-web Device-mobile

Actions field Device ID.


Update the value so your preferred field appears first in the coalesce() function.

Send Custom Language and Country Properties

Actions fields Language and Country


These fields are set by default with values from the context object.

Use Log Revenue v2 API
Device-web Device-mobile

Actions supports Revenue v2. Confirm revenue reporting is working as expected if you migrate from the Classic Amplitude destination where this setting was disabled

Advanced Amplitude (Actions) settings

Increment Traits

The traitsToIncrement setting increases a user property by some numerical value. If the user property does not have a value set yet, Segment initializes it with a value of 0. The trait must have a numerical value so it can be incremented.

In the following example, the Amplitude User property friendCount equals 4.

"traits" : {"$add": {"friendCount": 3} }
"traits" : {"$add": {"friendCount": 1} }

This page was last modified: 14 Aug 2024



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account