IOS SWIFT V1 IOS SWIFT V1/MODULE LIST

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 would like 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 CocoaPods or Carthage.

CocoaPods

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

pod 'tealium-swift/TealiumCore'
pod 'tealium-swift/TealiumCollect' //or 'tealium-swift/TealiumTagManagement'
pod 'tealium-swift/TealiumVisitorService'

The framework is auto-instantiated. It has a dependency on the TealiumCore pod, and one of the dispatch service pods (either TealiumCollect or TealiumTagManagement). Learn more about CocoaPods installation for iOS.

Carthage

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

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

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

    TealiumVisitorService.framework

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

    import TealiumCore
import TealiumCollect //or import TealiumTagManagement
import TealiumVisitorService

The framework is auto-instantiated. It has a dependency on TealiumCore, and at least one dispatch service (TealiumCore or TealiumTagManagement). No additional import statements are necessary.

Learn more about Carthage installation for iOS.

Visitor Data Object

The visitor profile is an object that contains native structs for each attribute type. Within the visitor profile object, there is a currentVisit property that allows you to distinguish visitor/visit attribute types. With the exception of audiences, each attribute value is accessible by ID using a subscript. The audiences attribute simply returns true/false if a visitor is a member of the audience queried via subscript. 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, name: String id: "tealiummobile\_demo\_103", name: "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 profile. The current visit profile does not contain Audiences or Badges. TealiumCurrentVisitProfile(dates: [DateTime(id: "5376", value: 1567536668080), DateTime(id: "10", value: 1567536668000)], booleans: [Boolean(id: "4530", value: true], numbers: [Number(id: "32", value: 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[String] id: "5211", value: ["green shirts", "red shirts", "blue shirts"]
strings id: String, value: String id: "5380", value: "green shirts"
tallies id: String, value: [TallyValue] id: "57", [[key: "category 1" count: 2.0], key: "category 2", count: 1.0]]
tallyValue key: String, count: Double [key: "category 1" count: 2.0]

arraysOfBooleans

Custom subscripting allows for querying the array of booleans value by id.

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

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return an array of booleans value
        if let arraysOfBooleans = profile.arraysOfBooleans?["5279"] {
            let numberOfPositiveBools = arraysOfBooleans.map { $0 == true }.count
            print(numberOfPositiveBools)
        }
}

arraysOfNumbers

Custom subscripting allows for querying the array of numbers value by id.

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

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return an array of numbers value
        if let arraysOfNumbers = profile. arraysOfNumbers?["5279"] {
            arraysOfNumbers.forEach { number in
        		if number > 3.0 {
        			// ... take action
        		}
            }
        }
}

arraysOfStrings

Custom subscripting allows for querying the array of strings value by id.

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

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

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

audiences

Custom subscripting allows for checking visitor audience membership by audience id and audience name.

Usage Description Type Example
profile.audiences Returns all audiences for which the visitor is a member. [Audience] [Audience(id: "tealiummobile\_demo\_103", name: "iOS Users"), Audience(id: "tealiummobile\_demo\_110", name: "Visitors - Known")]
profile.audiences[id: "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
profile.audiences[name: "ios users"] Returns true/false depending on whether or not the visitor is a member of the audience based on the name passed in. The name is case insensitive. Bool false

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return the current Audiences for which the user is assigned
        if let currentVisitorAudiences = profile.audiences {
            print("Visitor audiences: \(currentVisitorAudiences)")

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

            // Check if an Audience is assigned to a user by name
            if currentVisitorAudiences[name: "ios users"] {
                print("Visitor is a member of audience iOS Users")
                // ... Visitor is a member of this audience, take appropriate action
            }
        }
}

badges

Custom subscripting allows for querying the badge value by id.

Usage Description Type Example
profile.badges Returns all badges in the visitor profile. [Badge] [Badge(id: "2815", value: true), Badge(id: "2813", value: false)]
profile.badges["2815"] Returns true/false depending on whether or not the visitor is assigned the badge. Bool true

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

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

booleans

Custom subscripting allows for querying the boolean value by id.

Usage Description Type Example
profile.booleans Returns all the booleans in the visitor profile. [Boolean] [Boolean(id: "5784", value: true), Boolean(id: "1453", value: false)]
profile.booleans["4692"] Returns the boolean by id. Bool true

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return a boolean value
        if let booleanValue = profile. 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
profile. currentVisit Returns the current visit scoped attributes. TealiumCurrentVisitProfile TealiumCurrentVisitProfile (dates: [DateTime(id: "5376", value: 1567536668080), DateTime(id: "10", value: 1567536668000)], booleans: [Boolean(id: "4530", value: true], numbers: [Number(id: "32", value: 3.8)])
profile. currentVisit. ### Returns the desired attribute depending on ###. All the same methods liste above apply except for Audiences and Badges. These are exclusively visitor attributes and do not apply to the visit. Varies Varies

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

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

dates

Custom subscripting allows for querying the date value by id.

Usage Description Type Example
profile.dates Returns all the dates in the visitor profile. [DateTime] [DateTime(id: "22", value: 1567120112000), DateTime(id: "13", value: 1567120113245)]
profile.dates["4692"] Returns the date by id. Int 1567120112000

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return a date value
        if let date = profile.dates?["33"] {
            print(date)
            // .. take action
        }
}

numbers

Custom subscripting allows for querying the number value by id.

Usege Description Type Example
profile.numbers Returns all the numbers in the visitor profile. [Number] [Number(id: "83", value: 0.5714285714285714), Number(id: "1399", value: 2.0)]
profile.numbers["1399"] Returns the number by id. Double 4.82125

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return a number value
        if let number = profile. numbers?["1399"] {
            if number > 3.0 {
            	// ... take action
            }
        }
}

setsOfStrings

Custom subscripting allows for querying the set of strings value by id.

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

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

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

strings

Custom subscripting allows for querying the string value by id.

Usage Description Type Example
profile.strings Returns all the strings in the visitor profile. [VisitorString] [Number(id: "83", value: "Toy Truck"), Number(id: "5699", value: "Toy Tea Set")]
profile.strings["5699"] Returns the string by id. String "Toy Tea Set"

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return a string value
        if let string = profile.strings?["5699"] {
            print(string)
            // ... take action
        }
}

tallies and tallyValue

Custom subscripting allows for querying the tally by id, and to query the tally value by id.

Usage Description Type Example
profile.tallies Returns all the tallies in the visitor profile. [Tally] [Tally(id: "2983", value: [TallyValue(key: "red shirts category", count: 4.0), TallyValue(key: "green shirts category", count: 2.0)]), Tally(id: "5643", value: [TallyValue(key: "girls", count: 3.0), TallyValue(key: "womens", count: 1.0)]]
profile.tallies[tally: "1399"] Returns the tally by id. [TallyValue] [TallyValue(key: "girls", count: 3.0), TallyValue(key: "womens", count: 1.0)]
profile.tallies[tally: "1399", key: "womens"] Returns the tally by id. Double 3.0

Example usage:

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // Return an entire tally
        if let tally = profile.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 tallyValue = profile.tallies?[tally: "5381", key: "red shirts"]{
            print("Tally value for id 5381 and key 'red shirts': \(tallyValue)")
        }
}

API Reference

Class Tealium

The following API methods are available to act upon the updated visitor profile.

visitorService()

Usage Example:

class MyHelperClass {
    var tealium: Tealium?

    public init () {
        let config = TealiumConfig(account: "ACCOUNT",
                                   profile: "PROFILE",
                                   environment: "ENVIRONMENT",
                                   datasource: "DATASOURCE",
                                   optionalData: nil)
        config.addVisitorServiceDelegate(self)                           
	     config.setVisitorServiceRefresh(interval: 10)		
		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()?.#### // where #### is any public API method on the visitorProfile object - see other methods for examples
		}
	}
}

requestVisitorProfile()

This method triggers an immediate request to the VisitorService to retrieve the current profile. If the profile has been updated since the last fetch, the profileDidUpdate delegate method will be 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]?) {
        tealium?.track(title: title, data: data, completion: { success, \_, error in
            if error != nil {
                print("*** Track not completed because of error: \n\(String(describing: error))")
            }
            if success {
                print("*** Track with VisitorService completed ***")
                self.tealium?.visitorProfile()?.requestVisitorProfile()

            }
        })
    }

getCachedProfile()

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.

Example:

self.tealium?.visitorService()?.getCachedProfile(completion: { profile in
                guard let profile = profile else { return }
                if let json = try? JSONEncoder().encode(profile), let string = String(data: 					json, encoding: .utf8) {
                    print(string)
   		}
})
Parameters Description Example Value
completion: TealiumVisitorProfile?

removeAllVisitorServiceDelegates()

Removes all visitor profile delegates.

self.tealium?.visitorService()?.removeAllVisitorServiceDelegates()

addVisitorServiceDelegate()

Adds a new class conforming to VisitorServiceDelegate

self.tealium?.visitorService()?.addVisitorServiceDelegate(self)
Parameters Description Example
delegate: Class conforming to VisitorServiceDelegate ViewController, TealiumHelper

removeSingleDelegate()

Removes a specific visitor profile delegate.

Example:

self.tealium?.visitorService()?.removeSingleDelegate(self)
Parameters Description Example Value
delegate: Class conforming to VisitorServiceDelegate ViewController, TealiumHelper

Class: TealiumVisitorServiceDelegate

profileDidUpdate()

This method is called whenever the visitor profile was updated. This will most likely be called every time the requestVisitorProfile() method is used.

func profileDidUpdate(profile: TealiumVisitorProfile?) {
        guard let profile = profile else { return }

        // act on profile attributes
        print(profile.audiences)

        ...
}

Class: TealiumConfig

setVisitorServiceRefresh()

This allows you to set the frequency of visitor profile retrieval. The default value is 5 minutes for this setting. Use this method to adjust the frequency. Even if you add the requestVisitorProfile method to every tracking call, the profile will not be fetched every time unless you set this to 0.

let config = TealiumConfig(...)
config.setVisitorServiceRefresh(3)
Parameters Description Example
interval The frequency for which to fetch the visitor profile. Integer, minutes. (default: 5) 3

addVisitorServiceDelegate()

config.addVisitorServiceDelegate(self)

Add a delegate to an array of VisitorService delegates in order to use the profileDidUpdate delegate method. There can be multiple objects assigned as delegates.

Parameters Description Example
class responsible for the profile updates (delegate) ViewController, TealiumHelper

getVisitorServiceDelegates()

Returns a list of delegates assigned to the VisitorService module.

config.getVisitorServiceDelegates()

setVisitorServiceOverrideProfile()

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

config. setVisitorServiceOverrideProfile("PROFILE")

setVisitorServiceOverrideURL()

config. setVisitorServiceOverrideURL("https://overridden-subdomain.yourdomain.com/")

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

Release Notes

1.8.0

  • Initial release
"TagManagement Module "
Previous
TagManagement Module
Next
VolatileData Module
"VolatileData Module"