Ampli for iOS Swift SDK

Amplitude Data supports tracking analytics events from iOS apps written in Swift and Objective-C.

Quick start

Install the Amplitude SDK.
bash
```
pod 'AmplitudeSwift', '~> 1.0'
```
Install the Ampli CLI.
bash
```
npm install -g @amplitude/ampli
```
Pull the Ampli Wrapper into your project.
bash
```
ampli pull [--path ./Ampli]
```

swift

Ampli.instance.load(LoadOptions(
  environment: AmpliEnvironment.YourEnvironment
))

Identify users and set user properties.

swift

Ampli.instance.identify("userID", Identify(
    userProp: "A trait associated with this user"
))

Track events with strongly typed methods and classes.

swift

Ampli.instance.songPlayed(SongPlayed(songId: "song-1")
Ampli.instance.track(SongFavorited(songId: "song-2")

Flush events before application exit.
swift
```
Ampli.instance.flush()
```
Verify implementation status with CLI.
shell
```
ampli status [--update]
```

Install the SDK

Install the Amplitude Analytics iOS SDK with CocoaPods, Carthage, or Swift Package Manager.

Add the dependency to your Podfile:

ruby

platform :ios, '16.0'

target 'YourApp' do
  pod 'AmplitudeSwift', '~> 1.0'
end

Run pod install in the project directory.

Install the Ampli CLI

Install the Ampli CLI from Homebrew or npm.

bash

brew tap amplitude/ampli
brew install ampli

Pull the Ampli Wrapper into your project

Run the Ampli CLI pull command to log in to Amplitude Data and download the strongly typed Ampli Wrapper for your tracking plan. Run Ampli CLI commands from the project root directory.

bash

ampli pull

Attach properties to your source

After you add new events or properties to your tracking plan, attach them to your source in Amplitude Data. The ampli pull command only includes events and properties attached to the selected source. If you don't attach new properties to your source, they don't appear in the generated Ampli Wrapper code.

Use Ampli

Ampli generates a thin facade over the Amplitude SDK that provides convenience methods. The Ampli Wrapper also grants access to every method of the underlying Amplitude SDK through Ampli.instance.client. Refer to More details.

Import

Import the Amplitude SDK in your Swift file:

swift

import AmplitudeSwift

Load

Initialize Ampli in your code. The load() method accepts configuration option arguments:

swift

// Using API key directly
Ampli.instance.load(LoadOptions(
    client: LoadClientOptions(apiKey: AMPLITUDE_API_KEY)
))

// Using environment from tracking plan
Ampli.instance.load(LoadOptions(
    environment: AmpliEnvironment.YourEnvironment
))

Argument	Description
`LoadOptions`	Required. Specifies configuration options for the Ampli Wrapper.
`instance`	Required if `apiKey` isn't set. Specifies an Amplitude instance. By default, Ampli creates an instance for you.
`apiKey`	Required if `instance` isn't set. Specifies an API Key. This option overrides the default, which is the API Key configured in your tracking plan.
`environment`	Optional. Specifies the environment name from your tracking plan. Replace `YourEnvironment` with the actual environment name configured in your tracking plan.
`disabled`	Optional. Specifies whether the Ampli Wrapper does any work. When true, all calls to the Ampli Wrapper are no-ops. Useful in local or development environments.

Identify

Call identify() to identify a user in your app and associate all future events with their identity, or to set their properties.

Just as the Ampli Wrapper creates types for events and their properties, it creates types for user properties.

The identify() function accepts an optional userId, optional user properties, and optional options.

For example, your tracking plan contains a user property called userProp. The property's type is a string.

swift

Ampli.instance.identify("userID", Identify(
    requiredUserProp: "A trait associated with this user",
    optionalUserProp: "Another trait"
))

The options argument lets you pass Amplitude fields for this call, such as deviceId.

swift

Ampli.instance.identify("userID", Identify(), options: EventOptions(deviceId: "my_device_id"))

Group

Call setGroup() to associate a user with their group (for example, their department or company). The setGroup() function accepts a required groupType, and groupName.

swift

Ampli.instance.client.setGroup(groupType:"group type", groupName:"group name")

Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group performs the specific event, the count includes the group.

For example, you group users by organization using an orgId. Joe is in orgId 10, and Sue is in orgId 15. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.

When you set groups, define a groupType and groupName. In this example, orgId is the groupType and 10 and 15 are the values for groupName. Another example of a groupType is sport with groupName values like tennis and baseball.

Setting a group also sets groupType:groupName as a user property, and overwrites any existing groupName value set for that user's groupType, and the corresponding user property value. groupType is a string, and groupName can be either a string or an array of strings to indicate that a user belongs to multiple groups. For example, if Joe is in orgId 10 and 20, then the groupName is [10, 20].

Your code might look like this:

swift

Ampli.instance.client.setGroup(groupType: "orgID", groupName: ["10", "20"])

Track

To track an event, call the event's corresponding function. Every event in your tracking plan has its own function in the Ampli Wrapper. The call uses this structure:

swift

Ampli.instance.track(_ event: Event, options: EventOptions)

The options argument lets you pass Amplitude fields, like deviceID.

Set EventOptions through generic track. Ampli doesn't expose them on strongly typed event methods such as Ampli.instance.songPlayed(songId: 'id', songFavorited: true).

For example, your tracking plan contains an event called songPlayed with two required properties: songId and songFavorited. The property type for songId is string, and songFavorited is a boolean.

The event has two Amplitude fields defined: price and quantity.

swift

Ampli.instance.track(
    SongPlayed(songId: 'songId', songFavorited: true),
    options: EventOptions(
        deviceId: 'deviceId',
        price: 0.99,
        quantity: 1
    )
);

Ampli also generates a class for each event.

swift

let myEventObject = SongPlayed(
    songId: 'songId', // String,
    songFavorited: true, // Bool
);

Send all Event objects using the generic track method.

swift

Ampli.instance.track(SongPlayed(
    songId: 'songId', // String,
    songFavorited: true, // Bool
);

Flush

The Ampli Wrapper queues events and sends them on an interval based on the configuration. Ampli flushes the buffer automatically when it reaches flushQueueSize or flushInterval.

Call flush() to send any pending events immediately. The flush() method returns a promise you can use to confirm Ampli sent all pending events before continuing. Call flush() before application exit to send queued events.

swift

Ampli.instance.flush()

Ampli CLI

Pull

The pull command downloads the Ampli Wrapper code to your project. Run the pull command from the project root.

bash

ampli pull

Ampli prompts you to log in to your workspace and select a source.

bash

➜ ampli pull
Ampli project is not initialized. No existing `ampli.json` configuration found.
? Create a new Ampli project here? Yes
? Organization: Amplitude
? Workspace: My Workspace
? Source: My Source

Status

Verify that your code implements events with the status command:

bash

ampli status [--update]

The output displays status and indicates what events are missing.

bash

➜ ampli status
✘ Verifying event tracking implementation in source code
 ✔ Song Played (1 location)
 ✘ Song Stopped Called when a user stops playing a song.
Events Tracked: 1 missed, 2 total

Learn more about ampli status.

Was this helpful?