Analytics-Swift for iOS & Apple

With Analytics-Swift, you can send data from iOS, tvOS, iPadOS, WatchOS, macOS and Linux applications to any analytics or marketing tool without having to learn, test, or implement a new API every time. Analytics-Swift is compatible with both Swift and Objective-C applications.

Benefits of Analytics-Swift

Analytics-Swift provides several key benefits including improvements in stability, performance, and developer experience when compared to Analytics iOS (Classic).

Performance

Analytics-Swift offers improved performance when compared to Analytics iOS. For a more detailed overview, you can reference the blog post.

• Faster event processing and delivery
• Significantly lower CPU usage
• Small memory & disk usage footprint

Developer Experience

Analytics-Swift adds several improvements to the overall experience of using the core SDK, as well as improvements to the overall Plugin Architecture.

• Ability to use Type Safe data structures rather than just dictionaries.
• Simpler syntax and more developer friendly overall.
• More customization options than ever before.

Device Mode Transformations & Filtering

For the first time ever, developers can filter and transform their users’ events even before the events leave the mobile device. What’s more, these Filters & transformations can be applied dynamically (either through the Segment Dashboard, or Javascript uploaded to the workspace) and do not require any app updates.

Learn more about Destination Filters on Mobile, and Edge Functions on Mobile.

Getting started

To get started with the Analytics-Swift mobile library:

1. Create a Source in Segment.
   1. Go to Connections > Sources > Add Source.
   2. Search for Apple and click Add source.
2. Add the Analytics dependency to your application. Add the Swift package, git@github.com:segmentio/analytics-swift.git as a dependency through either of these 2 options:
   1. Your package.swift file
   2. Xcode
      1. Xcode 12: File > Swift Packages > Add Package Dependency
      2. Xcode 13: File > Add Packages…

   After installing the package, you can reference Analytics-Swift by importing Segment’s Analytics package with import Segment.

3. Initialize and configure the Analytics-Swift client. For example, in a lifecycle method such as didFinishLaunchingWithOptions in iOS:

    var analytics: Analytics? = nil

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            // Override point for customization after application launch.
            let configuration = Configuration(writeKey: "WRITE_KEY")
                .trackApplicationLifecycleEvents(true)
                .flushInterval(10)

            analytics = Analytics(configuration: configuration)
    }

  @import Segment;
  ...

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Override point for customization after application launch.
      SEGConfiguration *config = [[SEGConfiguration alloc] initWithWriteKey:@"WRITE_KEY"];
      config.trackApplicationLifecycleEvents = YES;
    
      _analytics = [[SEGAnalytics alloc] initWithConfiguration: config];    

      [self.analytics track:@"Example Event"];
      [self.analytics track:@"Example Properties" properties:@{@"email": @"sloth@segment.com"}];
    
      return YES;
  }

These are the options you can apply to configure the client:

Core tracking methods

Once you’ve installed the Analytics-Swift library, you can start collecting data through Segment’s tracking methods:

• Track
• Identify
• Screen
• Group
• Alias

Destinations

Destinations are the business tools or apps that Segment forwards your data to. Adding Destinations allow you to act on your data and learn more about your customers in real time.

See Segment’s documentation for device-mode destinations for a full list of supported device-mode plugins.

See Segment’s cloud-mode destinations for a full list of available cloud-mode destinations that Swift supports.

Segment offers support for two different types of destination connection modes: Cloud-mode and Device-mode. learn more about the differences between the two in the Segment Destination docs.

Tools and extensions

Analytics-Swift is built with extensibility in mind. Use the tools list below to improve data collection.

• Plugin architecture
• Typewriter
• Destination Filters
• Code samples

Proxying events

If you proxy your events through the apiHost config option, you must forward the batched events to https://api.segment.io/v1/b. The https://api.segment.io/v1/batch endpoint is reserved for events arriving from server-side sending, and proxying to that endpoint for your mobile events may result in unexpected behavior.

Telemetry

The Analytics-Swift SDK collects telemetry data on configuration and usage by default. This includes basic information on SDK setup, plugins and event types used, and basic error details. Segment downsamples the data to minimize traffic and doesn’t collect any personally identifiable information (PII) or event data.

You can disable telemetry at any time by setting Telemetry.shared.enable = false.

When internal errors or errors from plugins occur, the write key may be included with error data to help Segment identify the issue(s). You can disable this by setting Telemetry.shared.sendWriteKeyOnError = false.

Timestamps in Swift

Due to efficiency updates made to Segment’s Swift library, Segment now adds the sentAt timestamp to an event when the batch is complete and initially tried to the Segment API. This can impact the value of the timestamp field calculated by Segment if users are operating in an offline mode. More details on this change can be seen in Segment’s timestamp documentation.