VisitorService Module

Usage

The VisitorService module implements the Data Layer Enrichment feature of the Tealium Customer Data Hub.

Usage of this module is recommended if you are licensed for Tealium AudienceStream and you want to use the visitor profile to enhance the user experience in your mobile application. If you are not licensed for AudienceStream, usage of this module is not recommended as no visitor profile is returned.

The following platforms are supported:

iOS
tvOS
watchOS
macOS

Install

Install the VisitorService module with Swift Package Manager, CocoaPods or Carthage.

Swift Package Manager (Recommended)

Supported in version 1.9.0+, the Swift Package Manager is the recommended and simplest way to install the Tealium Swift library:

In your Xcode project, select File > Add Package Dependencies.
Enter the repository URL: https://github.com/tealium/tealium-swift
Configure the version rules. Typically, "Up to next major" is recommended. If the current Tealium Swift library version does not appears in the list, then reset your Swift package cache.
Select the VisitorService, Core, and either Collect or TagManagement modules from the list of modules to install and add it each of your app targets in your Xcode project, under Frameworks and Libraries.

CocoaPods

To install the VisitorService module with CocoaPods, add the following pods to your Podfile:

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

Learn more about the CocoaPods installation for iOS.

Carthage

To install the VisitorService module with Carthage, following these steps:

Go to the app target’s General configuration page in Xcode.
Add the following framework to the Embedded Binaries section:
```
TealiumVisitorService.framework
```

To setup the VisitorService module, add the following required import statements to your project:

import TealiumCore
import TealiumCollect //or import TealiumTagManagement
import TealiumVisitorService

Learn more about the Carthage installation for iOS.

Initialize

To initialize the module, verify that it’s specified on the TealiumConfig collectors property

config.collectors = [Collectors.VisitorService]

Visitor Data Object

The visitor profile is an object that contains friendly names for each attribute. There is a currentVisit property that allows you to distinguish visitor/visit attribute types. Access each attribute value by ID using a subscript. If the attribute does not exist, nil is returned. See the below list for examples.

Attribute Types

Parameters	Properties	Value
`arraysOfBooleans`	id: String, value: [Bool]	`id: "5129", value: [true,false,true,true]`
`arraysOfNumbers`	id: String, value: [Double]	`id: "57", value: [4.82125, 16.8, 0.5714285714285714]`
`arraysOfStrings`	id: String, value: [String]	`id: "5213", value: ["green shirts", "green shirts", "blue shirts"]`
`audiences`	id: String, value: String	`id: "tealiummobile\_demo\_103", value: "iOS Users"`
`badges`	id: String, value: Bool	`id: "2815", value: true`
`booleans`	id: String, value: Bool	`id: "4868", value: true`
`currentVisit`	All attributes for current visit visitorProfile. The current visit profile does not contain Audiences or Badges.	`TealiumCurrentVisitProfile(dates: ["5376": 1567536668080, "10": 1567536668000], booleans: ["4530": true], numbers: ["32": 3.8])`
`dates`	id: String, value: Int	`id: "22", value: 1567120112000`
`numbers`	id: String, value: Double	`id: "5728", value: 4.82125`
`setOfStrings`	id: String, value: Set	`id: "5211", value: ["green shirts", "red shirts", "blue shirts"]`
`strings`	id: String, value: String	`id: "5380", value: "green shirts"`
`tallies`	id: String, value: [String:Double]	`"57": [["category 1": 2.0], "category 2": 1.0]]`
`tallyValue`	id: String, value: Double	`["category 1": 2.0]`

If an Audience or Badge is not assigned, nil is returned.

`arraysOfBooleans`

Usage	Description	Type	Example
`visitorProfile.arraysOfBooleans`	Returns all the arrays of booleans in the visitor profile.	`[String: [Bool]]`	`["2333": [true,false], "1123": [true,true]]`
`visitorProfile.arraysOfBooleans["2815"]`	Returns the array of booleans by id.	`[Bool]`	`[true,true]`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return an array of booleans value
    if let arraysOfBooleans = visitorProfile.arraysOfBooleans?["5279"] {
        let numberOfPositiveBools = arraysOfBooleans.filter { $0 == true }.count
        print(numberOfPositiveBools)
    }
}

`arraysOfNumbers`

Usage	Description	Type	Example
`visitorProfile.arraysOfNumbers`	Returns all the arrays of numbers in the visitor profile.	`[String: [Double]]`	`["2333": [2.0, 1.0], "1123": [4.82125, 3.0]]`
`visitorProfile.arraysOfNumbers["2815"]`	Returns the array of numbers by id.	`[Double]`	`[4.82125, 3.0]`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return an array of numbers value
    if let arraysOfNumbers = visitorProfile.arraysOfNumbers?["5279"] {
        arraysOfNumbers.forEach { number in
    		if number > 3.0 {
    			// ... take action
    		}
        }
    }
}

`arraysOfStrings`

Usage	Description	Type	Example
`visitorProfile.arraysOfStrings`	Returns all the arrays of strings in the visitor profile.	`[String: [String]]`	`["1033": ["Foundation", "Perfume"], "3390": ["Bootleg Jeans", "Dresses"]]`
`visitorProfile.arraysOfStrings["3390"]`	Returns the array of strings by id.	`[String]`	`["Bootleg Jeans", "Dresses"]`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return an array of strings value
    if let arraysOfStrings = visitorProfile.arraysOfStrings?["3390"] {
        arraysOfStrings.forEach { string in
    		if string.lowercased().contains("Jeans") {
    			// ... take action
    		}
        }
    }
}

`audiences`

Usage	Description	Type	Example
`visitorProfile.audiences`	Returns all audiences for which the visitor is a member.	`[String: String]`	`["tealiummobile\_demo\_103": "iOS Users", "tealiummobile\_demo\_110": "Visitors - Known"]`
`visitorProfile.audiences["103"]`	Returns true/false depending on whether or not the visitor is a member of the audience based on the id passed in.	`Bool`	`true`

If an Audience is not assigned, nil is returned.

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return the current Audiences for which the user is assigned
    if let audiences = visitorProfile.audiences {
        print("Visitor audiences: \(audiences)")

        // Check if an Audience is assigned to a user by id
        if audiences["account_profile_106"] != nil {
            print("Visitor is a member of audience id 106")
            // ... Visitor is a member of this audience, take appropriate action
        }

    }
}

`badges`

Usage	Description	Type	Example
`visitorProfile.badges`	Returns all badges in the visitor profile.	`[String: Bool]`	`["2815": true, "2813": true]`
`visitorProfile.badges["2815"]`	Returns true/false depending on whether or not the visitor is assigned the badge.	`Bool`	`true`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a badge value
    if let badgeAssigned = visitorProfile.badges?["5279"] {
        print(badgeAssigned ? "Badge id 5279 is assigned" : "Badge id 5945 is not assigned")
    }
}

If a Badge is not assigned, nil is returned.

`booleans`

Usage	Description	Type	Example
`visitorProfile.booleans`	Returns all the booleans in the visitor profile.	`[String: Bool]`	`["5784": true, "1453": false]`
`visitorProfile.booleans["4692"]`	Returns the boolean by id.	`Bool`	`true`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a boolean value
    if let booleanValue = visitorProfile.booleans?["4479"] {
        if booleanValue {
        	// ... do something
        }
    }
}

`currentVisit`

Access to the attributes for the current visit instead of the lifetime attributes for a visitor.

Usage	Description	Type	Example
`visitorProfile.currentVisit`	Returns the current visit scoped attributes.	`TealiumCurrentVisitProfile`	`TealiumCurrentVisitProfile(dates: ["5376": 1567536668080, "10": 1567536668000], booleans: ["4530": true], numbers: ["32": 3.8])`
`visitorProfile.currentVisit.###`	Returns the desired attribute depending on ###. All the same methods listed above apply except for Audiences and Badges. These are exclusively visitor attributes and do not apply to the visit.	Varies	Varies

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a current visit string attribute
    if let currentVisit = visitorProfile.currentVisit,
       let string = currentVisit.strings?["34"] {
        print(string)
        // ... take action
    }
}

`dates`

Usage	Description	Type	Example
`visitorProfile.dates`	Returns all the dates in the visitor profile.	`[String: Int]`	`["25": 1567120112000, "13": 1567120145666]`
`visitorProfile.dates["4692"]`	Returns the date by id.	`Int`	`1567120112000`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a date value
    if let date = visitorProfile.dates?["33"] {
        print(date)
        // .. take action
    }
}

`numbers`

Usege	Description	Type	Example
`visitorProfile.numbers`	Returns all the numbers in the visitor profile.	`[String: Double]`	`["83": 0.5714285714285714, "1399": 2.0]`
`visitorProfile.numbers["1399"]`	Returns the number by id.	`Double`	`4.82125`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a number value
    if let number = visitorProfile.numbers?["1399"] {
        if number > 3.0 {
        	// ... take action
        }
    }
}

`setsOfStrings`

Usage	Description	Type	Example
`visitorProfile.setsOfStrings`	Returns all the sets of strings in the visitor profile.	`[String: Set<String>]`	`["9938": ["shirts"], "2300": ["Luxury Couch 1", "Luxury Couch 2"]]`
`visitorProfile.setsOfStrings["2300"]`	Returns the set of strings by id.	`Set<String>`	`["Luxury Couch 1", "Luxury Couch 2"]`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return an set of strings value
    if let setOfStrings = visitorProfile.setsOfStrings?["5279"] {
        if setOfStrings.contains("toys") {
        	// ... take action
        }
    }
}

`strings`

Usage	Description	Type	Example
`visitorProfile.strings`	Returns all the strings in the visitor profile.	`String`	`"83": "Toy Truck", "5699": "Toy Tea Set"]`
`visitorProfile.strings["5699"]`	Returns the string by id.	`String`	`"Toy Tea Set"`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return a string value
    if let string = visitorProfile.strings?["5699"] {
        print(string)
        // ... take action
    }
}

`tallies`

Usage	Description	Type	Example
`visitorProfile.tallies`	Returns all the tallies in the visitor profile.	`[String: [String: Double]]`	`["2983": ["red shirts category": 4.0, "green shirts category": 2.0], "5643": ["girls": 3.0, "womens": 1.0]]`]
`visitorProfile.tallies["1399"]`	Returns the tally by id.	`[String: Double]`	`["girls": 3.0, "womens": 1.0]`
`visitorProfile.tallies["1399"]["womens"]`	Returns the tally by id.	`Double`	`3.0`

Example usage:

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Return an entire tally
    if let tally = visitorProfile.tallies?["1399"] {
        print("Tally id 5377: \(tally)")
    }

    // Return a tally value by using the tally id and the key for the value desired
    if let tally = visitorProfile.tallies?["5381"], let tallyValue = tally["red shirts"] {
        print("Tally value for id 5381 and key 'red shirts': \(tallyValue)")
    }
}

API Reference

Class `Tealium`

The following summarizes the commonly used methods and properties of the VisitorService module.

Method/Property	Description
`cachedProfile`	Returns the most recently-retrieved visitor profile from persistent storage, without triggering a new request
`requestVisitorProfile()`	Triggers an immediate request to the VisitorService to retrieve the current visitor profile
`visitorService`	The VisitorService module property

`cachedProfile`

Returns the most recently-retrieved visitor profile from persistent storage, without triggering a new request. Useful in situations where there is no internet connection, but a prior successful request has been made.

Usage example:

let profile = self.tealium?.visitorService?.cachedProfile
guard let json = try? JSONEncoder().encode(profile),
    let cachedProfileString = String(data: json, encoding: .utf8) else {
        return
}
print(cachedProfileString)

`requestVisitorProfile()`

Triggers an immediate request to the VisitorService to retrieve the current visitor profile. If the profile has been updated since the last fetch, the didUpdate() delegate method is called.

This method is called automatically whenever a track request is sent, if your visitor profile refresh interval is set to 0. If you have a higher value set for the refresh interval, then you may call this method to retrieve the profile instantly, without waiting for the next scheduled update.

self.tealium?.visitorService?.requestVisitorProfile()

Usage example:

func track(title: String, data: [String: Any]?) {
   let tealEvent = TealiumEvent(title, dataLayer: data)
   tealium?.track(tealEvent)
   tealium?.visitorService?.requestVisitorProfile()
}

`visitorService`

The VisitorService module.

self.tealium?.visitorService?.####

The #### is any public API method on the visitorService object. The following is a full usage example:

class MyHelperClass {
    var tealium: Tealium?

    public init () {
        let config = TealiumConfig(account: "ACCOUNT",
            profile: "PROFILE",
            environment: "ENVIRONMENT",
            datasource: "DATASOURCE",
            optionalData: nil)

        config.visitorServiceDelegate = self
        config.visitorServiceRefresh = .every(10, .minutes)

        self.tealium = Tealium(config) {
            // Note: this is inside the completion block after initialization

            // self.tealium is guaranteed to be initialized inside the completion block
            self.tealium?.visitorService?.####
        }
    }
}

Class: `VisitorServiceDelegate`

The following summarizes the commonly used methods and properties of the VisitorService module.

Method/Property	Description
`didUpdate()`	Callback method that returns the updated visitor profile when the profile has updated.

`didUpdate()`

Callback method that returns the updated visitor profile when the profile has updated, or when the requestVisitorProfile() method is called. This depends on the set value of the refresh interval, which default to 5 minutes.

func didUpdate(visitorProfile: TealiumVisitorProfile) {
    // Act on profile attributes
    print(visitorProfile.audiences)
    //...
}

Parameter	Description	Example
`TealiumVisitorProfile`	Tealium visitor profile	`visitorProfile`

Class: `TealiumConfig`

The following summarizes the commonly used methods and properties of the VisitorService module.

Method/Property	Description
`visitorServiceDelegate`	Set a delegate to use the `didUpdate` delegate method
`visitorServiceOverrideProfile`	Overrides the profile from which to fetch the visitor profile
`visitorServiceOverrideURL`	Overrides the base URL from which the visitor profile is retrieved
`visitorServiceRefresh`	Sets the frequency of visitor profile retrieval

`visitorServiceDelegate`

Set a delegate to use the didUpdate delegate method.

config.visitorServiceDelegate = self

Type	Description	Example
`Class`	Class responsible for the profile updates (delegate)	`AnalyticsManager`, `TealiumHelper`

Usage example:

func start() {
      let config = TealiumConfig(account: "ACCOUNT",
                                 profile: "NAME",
                                 environment: "ENVIRONMENT",
                                 datasource: "DATASOURCE",
                                 optionalData: nil)
      // Tealium VisitorService module config methods
      config.visitorServiceDelegate = self
  }

extension TealiumHelper: VisitorServiceDelegate {
    func didUpdate(visitorProfile: TealiumVisitorProfile) {
        if let json = try? JSONEncoder().encode(visitorProfile),
           let string = String(data: json, encoding: .utf8) {
            print(string)
        }
    }
}

`visitorServiceOverrideProfile`

Overrides the profile from which to fetch the visitor profile. Align it with the profile used for data collection in the Collect module.

config.visitorServiceOverrideProfile = "PROFILE"

Type	Description	Example
`String`	Sets the Audience Stream profile from which to fetch the visitor profile	`"main"`

Usage example:

func start() {
      let config = TealiumConfig(account: "ACCOUNT",
                                 profile: "NAME",
                                 environment: "ENVIRONMENT",
                                 datasource: "DATASOURCE",
                                 optionalData: nil)
      // Tealium Visitor Service module config methods
      config.visitorServiceOverrideProfile = "main"
  }

`visitorServiceOverrideURL`

Overrides the base URL from which the visitor profile is retrieved. ACCOUNT, PROFILE, and visitor ID are automatically appended to the URL.

config.visitorServiceOverrideURL = "https://overridden-subdomain.yourdomain.com/"

Type	Description	Example
`String`	Sets the URL from which to fetch the visitor profile	`"https://overridden-subdomain.yourdomain.com/"`

Usage example:

func start() {
      let config = TealiumConfig(account: "ACCOUNT",
                                 profile: "NAME",
                                 environment: "ENVIRONMENT",
                                 datasource: "DATASOURCE",
                                 optionalData: nil)
      // Tealium Visitor Service module config methods
      config.visitorServiceOverrideURL = "https://overridden-subdomain.yourdomain.com/"
  }

`visitorServiceRefresh`

Use this property to adjust the frequency of visitor profile retrieval. The default value is 5 minutes. Even if you add the requestVisitorProfile() method to every tracking call, the profile is not fetched every time unless you set this to 0.

let config = TealiumConfig(...)
config.visitorServiceRefresh = .every(3, .seconds)

RefreshInterval options: seconds, minutes, or hours

Parameters	Description	Example
`.every(Int, RefreshInterval)`	The frequency for which to fetch the visitor profile. (default: `.every(5, .minutes)`)	`.every(15, .seconds)`

Usage example:

func start() {
      let config = TealiumConfig(account: "ACCOUNT",
                                 profile: "NAME",
                                 environment: "ENVIRONMENT",
                                 datasource: "DATASOURCE",
                                 optionalData: nil)
      // Tealium Visitor Service module config methods
      config.visitorServiceRefresh = .every(3, .seconds)
  }

Release Notes

2.0.0

High Impact Changes

Updated TealiumVisitorProfile to be more performant
Removed multicast delegate capability for simplicity
Removed completion from cached profile method

Low Impact Changes

Added more options to refresh interval
Updated class names for consistency
Updated delegate method signature
Improved tests

1.8.0

Initial release

Usage

Install

Swift Package Manager (Recommended)

CocoaPods

Carthage

Initialize

Visitor Data Object

arraysOfBooleans

arraysOfNumbers

arraysOfStrings

audiences

badges

booleans

currentVisit

dates

numbers

setsOfStrings

strings

tallies

API Reference

Class Tealium

cachedProfile

requestVisitorProfile()

visitorService

Class: VisitorServiceDelegate

didUpdate()

Class: TealiumConfig

visitorServiceDelegate

visitorServiceOverrideProfile

visitorServiceOverrideURL

visitorServiceRefresh

Release Notes

`arraysOfBooleans`

`arraysOfNumbers`

`arraysOfStrings`

`audiences`

`badges`

`booleans`

`currentVisit`

`dates`

`numbers`

`setsOfStrings`

`strings`

`tallies`

Class `Tealium`

`cachedProfile`

`requestVisitorProfile()`

`visitorService`

Class: `VisitorServiceDelegate`

`didUpdate()`

Class: `TealiumConfig`

`visitorServiceDelegate`

`visitorServiceOverrideProfile`

`visitorServiceOverrideURL`

`visitorServiceRefresh`