Moments API Module (now Context API)

Moments API has been renamed to Context API. For full product documentation, see About Context API.

The Context API module enables you to retrieve detailed information about visitor profiles from the Tealium AudienceStream. This information can be used to enhance the customer experience in your app by accessing various attributes such as audiences, badges, strings, booleans, dates, and numbers.

Supported Platforms

The following platforms support the Context API module:

• iOS
• macOS
• tvOS
• watchOS

Install

Install the Context API module using Swift Package Manager, CocoaPods, or Carthage.

Swift Package Manager (Recommended)

1. In your Xcode project, select File > Swift Packages > Add Package Dependency
2. Enter the repository URL: https://github.com/tealium/tealium-swift
3. Configure the version rules. Typically, "Up to next major" is recommended. If the current Tealium Swift library version does not appear in the list, reset your Swift package cache.
4. Select the TealiumMomentsAPI, TealiumCore, and either TealiumCollect or TealiumTagManagement modules from the list of modules to install and add them to each of your app targets in your Xcode project, under Frameworks and Libraries.

CocoaPods

Add the following pods to your Podfile:

pod 'tealium-swift/Core'
pod 'tealium-swift/Collect' // or 'tealium-swift/TagManagement'
pod 'tealium-swift/MomentsAPI'

Carthage

1. Go to the app target’s General configuration page in Xcode.

2. Add the following framework to the Embedded Binaries section:

   TealiumMomentsAPI.xcframework
   

3. Add the required import statements to your project:

   import TealiumCore
   import TealiumCollect // or import TealiumTagManagement
   import TealiumMomentsAPI
   

Usage

Initialize

To initialize the module, ensure it’s specified on the TealiumConfig collectors property.

config.collectors = [Collectors.MomentsAPI]
config.momentsAPIRegion = .us_east // See possible region options below

Setting the region is mandatory. The Context API module will not initialize if it’s missing.

Fetch Visitor Data

Call the fetchEngineResponse method to retrieve personalized visitor data. This should be called whenever updated visitor information is needed, for example, to power in-app personalization use cases.

func fetchMoments(engineId: String, completion: @escaping (Result<EngineResponse, Error>) -> Void) {
    tealium?.momentsAPI?.fetchEngineResponse(engineID: engineId) { engineResponse in
        switch engineResponse {
        case .success(let response):
            print("String attributes:", response.strings ?? [])
            print("Boolean attributes:", response.booleans ?? [])
            print("Audiences:", response.audiences ?? [])
            print("Date attributes:", response.dates ?? [:])
            print("Badges:", response.badges ?? [])
            print("Numbers:", response.numbers ?? [:])
        case .failure(let error):
            print("Error fetching moments:", error.localizedDescription)
            if let suggestion = (error as? LocalizedError)?.recoverySuggestion {
                print("Recovery suggestion:", suggestion)
            }
        }
        completion(engineResponse)
    }
}

Visitor Profile Data

The EngineResponse object contains various types of attributes returned by the Context API. The following table shows the available properties and their data types:

Configuration Options

Region

Configure the Context API region according to where your AudienceStream profile resides. If uncertain, consult your account manager.

config.momentsAPIRegion = .us_east

The custom option allows for future expansion and should not be used unless directed.

Referrer

For added security, you can specify a referrer URL. This URL must match the “Domain Allow List” in the Tealium UI, or the Context API will not return any data. The default referrer URL is:

https://tags.tiqcdn.com/utag/{account}/{profile}/{environment}/mobile.html

Specify a custom referrer URL as shown below:

let config = TealiumConfig(
    account: "tealiummobile",
    profile: "demo",
    environment: "prod"
)
config.momentsAPIReferrer = "https://example.com/"
tealium = Tealium(config: config) { _ in
    // Initialization complete
}

Troubleshooting

Common Errors

You may encounter errors when requesting data from the Context API. The following table shows the errors that could occur: