Merge branch 'release/5.4.0'

CHANGELOG

@@ -1,3 +1,9 @@
+Version 5.4.0 (2023-07-12)
+--------------------------
+Add Snowplow ecommerce events and entities (#800)
+Increase interval for updating platform context properties from 0.1s to 1s (#798)
+Expose property for retrieving payload in ConsentDocument that was removed in v5 (#804)
+
 Version 5.3.1 (2023-07-06)
 --------------------------
 Fix incorrect date deserialization when reading the install timestamp from 1.7 version of the tracker (#801)

SnowplowTracker.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
  s.name = "SnowplowTracker"
- s.version = "5.3.1"
+ s.version = "5.4.0"
  s.summary = "Snowplow event tracker for iOS, macOS, tvOS, watchOS for apps and games."
  s.description = <<-DESC
  Snowplow is a mobile and event analytics platform with a difference: rather than tell our users how they should analyze their data, we deliver their event-level data in their own data warehouse, on their own Amazon Redshift or Postgres database, so they can analyze it any way they choose. Snowplow mobile is used by data-savvy games companies and app developers to better understand their users and how they engage with their games and applications. Snowplow is open source using the business-friendly Apache License, Version 2.0 and scales horizontally to many billions of events.

Sources/Core/Subject/PlatformContext.swift

@@ -20,7 +20,7 @@ import UIKit
 /// Manages a dictionary (Payload) with platform context. Some properties for mobile platforms are updated on fetch in set intervals.
 class PlatformContext {
  private var platformDict: Payload = Payload()
- private var mobileDictUpdateFrequency: TimeInterval = 0.1
+ private var mobileDictUpdateFrequency: TimeInterval = 1.0
  private var networkDictUpdateFrequency: TimeInterval = 10.0
  private var lastUpdatedEphemeralMobileDict: TimeInterval = 0.0
  private var lastUpdatedEphemeralNetworkDict: TimeInterval = 0.0
@@ -37,7 +37,7 @@ class PlatformContext {
  /// - deviceInfoMonitor: Device monitor for fetching platform information
  /// - Returns: a PlatformContext object
  init(platformContextProperties: [PlatformContextProperty]? = nil,
- mobileDictUpdateFrequency: TimeInterval = 0.1,
+ mobileDictUpdateFrequency: TimeInterval = 1.0,
  networkDictUpdateFrequency: TimeInterval = 10.0,
  deviceInfoMonitor: DeviceInfoMonitor = DeviceInfoMonitor()) {
  self.platformContextProperties = platformContextProperties

Sources/Core/Tracker/EcommerceControllerImpl.swift

@@ -0,0 +1,37 @@
+// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License
+// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at
+// http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on
+// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the Apache License Version 2.0 for the specific
+// language governing permissions and limitations there under.
+
+import Foundation
+
+class EcommerceControllerImpl: Controller, EcommerceController {
+
+ func setEcommerceScreen(_ screen: EcommerceScreenEntity) {
+ let plugin = PluginConfiguration(identifier: "ecommercePageTypePluginInternal")
+ _ = plugin.entities { _ in [screen.entity] }
+ serviceProvider.addPlugin(plugin: plugin)
+ }
+
+ func setEcommerceUser(_ user: EcommerceUserEntity) {
+ let plugin = PluginConfiguration(identifier: "ecommerceUserPluginInternal")
+ _ = plugin.entities { _ in [user.entity] }
+ serviceProvider.addPlugin(plugin: plugin)
+ }
+
+ func removeEcommerceScreen() {
+ serviceProvider.removePlugin(identifier: "ecommercePageTypePluginInternal")
+ }
+
+ func removeEcommerceUser() {
+ serviceProvider.removePlugin(identifier: "ecommerceUserPluginInternal")
+ }
+}

Sources/Core/Tracker/ServiceProvider.swift

@@ -109,7 +109,14 @@ class ServiceProvider: NSObject, ServiceProviderProtocol {
  return mediaController
  }
 
- // Configurations
+ private var _ecommerceController: EcommerceController?
+ var ecommerceController: EcommerceController {
+ if let controller = _ecommerceController { return controller }
+ let ecommerceController = EcommerceControllerImpl(serviceProvider: self)
+ _ecommerceController = ecommerceController
+ return ecommerceController
+ }
+
  private(set) var networkConfiguration = NetworkConfiguration()
  private(set) var trackerConfiguration = TrackerConfiguration()
  private(set) var emitterConfiguration = EmitterConfiguration()

Sources/Core/Tracker/ServiceProviderProtocol.swift

@@ -34,6 +34,7 @@ protocol ServiceProviderProtocol: AnyObject {
  var subjectConfiguration: SubjectConfiguration { get }
  var sessionConfiguration: SessionConfiguration { get }
  var gdprConfiguration: GDPRConfiguration { get }
+ var ecommerceController: EcommerceController { get }
  var pluginConfigurations: [PluginIdentifiable] { get }
  func addPlugin(plugin: PluginIdentifiable)
  func removePlugin(identifier: String)

Sources/Core/Tracker/Tracker.swift

@@ -471,11 +471,12 @@ class Tracker: NSObject {
  setApplicationInstallEventTimestamp(event)
  addBasicProperties(to: payload, event: event)
  addStateMachinePayloadValues(event: event)
- event.wrapProperties(to: payload, base64Encoded: base64Encoded)
-
+
  // Context entities
  addBasicContexts(event: event)
  addStateMachineEntities(event: event)
+
+ event.wrapProperties(to: payload, base64Encoded: base64Encoded)
  event.wrapContexts(to: payload, base64Encoded: base64Encoded)
 
  // Decide whether to track the event or not

Sources/Core/Tracker/TrackerControllerImpl.swift

@@ -53,6 +53,10 @@ class TrackerControllerImpl: Controller, TrackerController {
  var media: MediaController {
  return serviceProvider.mediaController
  }
+
+ var ecommerce: EcommerceController {
+ return serviceProvider.ecommerceController
+ }
 
  // MARK: - Control methods
 

Sources/Core/TrackerConstants.swift

@@ -14,7 +14,7 @@
 import Foundation
 
 // --- Version
-let kSPRawVersion = "5.3.1"
+let kSPRawVersion = "5.4.0"
 #if os(iOS)
 let kSPVersion = "ios-\(kSPRawVersion)"
 #elseif os(tvOS)
@@ -60,6 +60,16 @@ let kSPErrorSchema = "iglu:com.snowplowanalytics.snowplow/application_error/json
 let kSPApplicationInstallSchema = "iglu:com.snowplowanalytics.mobile/application_install/jsonschema/1-0-0"
 let kSPGdprContextSchema = "iglu:com.snowplowanalytics.snowplow/gdpr/jsonschema/1-0-0"
 let kSPDiagnosticErrorSchema = "iglu:com.snowplowanalytics.snowplow/diagnostic_error/jsonschema/1-0-0"
+let ecommerceActionSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2"
+let ecommerceProductSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0"
+let ecommerceCartSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/cart/jsonschema/1-0-0"
+let ecommerceTransactionSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0"
+let ecommerceTransactionErrorSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/transaction_error/jsonschema/1-0-0"
+let ecommerceCheckoutStepSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/checkout_step/jsonschema/1-0-0"
+let ecommercePromotionSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/promotion/jsonschema/1-0-0"
+let ecommerceRefundSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/refund/jsonschema/1-0-0"
+let ecommerceUserSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0"
+let ecommercePageSchema = "iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0"
 
 // --- Event Keys
 let kSPEventPageView = "pv"

Sources/Snowplow/Controllers/TrackerController.swift

@@ -56,6 +56,9 @@ public protocol TrackerController: TrackerConfigurationProtocol {
  /// Media controller for managing media tracking instances and tracking media events.
  @objc
  var media: MediaController { get }
+ /// Ecommerce controller for managing ecommerce entity addition.
+ @objc
+ var ecommerce: EcommerceController { get }
  /// Track the event.
  /// The tracker will take care to process and send the event assigning `event_id` and `device_timestamp`.
  /// - Parameter event: The event to track.

Sources/Snowplow/Ecommerce/EcommerceController.swift

@@ -0,0 +1,39 @@
+// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License
+// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at
+// http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on
+// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the Apache License Version 2.0 for the specific
+// language governing permissions and limitations there under.
+
+import Foundation
+
+/**
+ Controller for managing Ecommerce entities.
+ */
+@objc(SPEcommController)
+public protocol EcommerceController {
+
+ /// Add an ecommerce Screen/Page entity to all subsequent events.
+ /// - Parameter screen: A EcommScreenEntity.
+ @objc
+ func setEcommerceScreen(_ screen: EcommerceScreenEntity)
+
+ /// Add an ecommerce User entity to all subsequent events.
+ /// - Parameter user: A EcommUserEntity.
+ @objc
+ func setEcommerceUser(_ user: EcommerceUserEntity)
+
+ /// Stop adding a Screen/Page entity to events.
+ @objc
+ func removeEcommerceScreen()
+
+ /// Stop adding a User entity to events.
+ @objc
+ func removeEcommerceUser()
+}

Sources/Snowplow/Ecommerce/Entities/CartEntity.swift

@@ -0,0 +1,56 @@
+// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License
+// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at
+// http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on
+// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the Apache License Version 2.0 for the specific
+// language governing permissions and limitations there under.
+
+import Foundation
+
+/**
+ Provided to certain Ecommerce events. The Cart properties will be sent with the event as a Cart entity.
+ Entity schema: `iglu:com.snowplowanalytics.snowplow.ecommerce/cart/jsonschema/1-0-0`
+ */
+@objc(SPCartEntity)
+public class CartEntity: NSObject {
+ /// The total value of the cart after this interaction.
+ @objc
+ public var totalValue: Decimal
+
+ /// The currency used for this cart (ISO 4217).
+ @objc
+ public var currency: String
+
+ /// The unique ID representing this cart.
+ @objc
+ public var cartId: String?
+
+ internal var entity: SelfDescribingJson {
+ var data: [String : Any] = [
+ "total_value": totalValue,
+ "currency": currency
+ ]
+ if let cartId = cartId { data["cart_id"] = cartId }
+
+ return SelfDescribingJson(schema: ecommerceCartSchema, andData: data)
+ }
+
+ /// - Parameter totalValue: The total value of the cart after this interaction.
+ /// - Parameter currency: The currency used for this cart (ISO 4217).
+ /// - Parameter cartId: The unique ID representing this cart.
+ @objc
+ public init(
+ totalValue: Decimal,
+ currency: String,
+ cartId: String? = nil) {
+ self.totalValue = totalValue
+ self.currency = currency
+ self.cartId = cartId
+ }
+}

Sources/Snowplow/Ecommerce/Entities/EcommerceScreenEntity.swift

@@ -0,0 +1,56 @@
+// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License
+// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at
+// http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on
+// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the Apache License Version 2.0 for the specific
+// language governing permissions and limitations there under.
+
+import Foundation
+
+/**
+ Attach Ecommerce Screen (Page) details to events. It is designed to help with grouping insights by 
+ screen/page type, e.g. Product description, Product list, Home.
+ Entity schema: `iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0`
+ */
+@objc(SPEcommerceScreenEntity)
+public class EcommerceScreenEntity: NSObject {
+ /// The type of screen that was visited, e.g. homepage, product details, cart, checkout, etc.
+ @objc
+ public var type: String
+
+ /// The language that the screen is based in.
+ @objc
+ public var language: String?
+
+ /// The locale version of the app that is running.
+ @objc
+ public var locale: String?
+
+ internal var entity: SelfDescribingJson {
+ var data: [String : Any] = ["type": type]
+ if let language = language { data["language"] = language }
+ if let locale = locale { data["locale"] = locale }
+
+ return SelfDescribingJson(schema: ecommercePageSchema, andData: data)
+ }
+
+ /// - Parameter type: The type of screen that was visited, e.g. homepage, product details, cart, checkout, etc.
+ /// - Parameter language: The language that the screen is based in.
+ /// - Parameter locale: The locale version of the app that is running.
+ @objc
+ public init(
+ type: String,
+ language: String? = nil,
+ locale: String? = nil
+ ) {
+ self.type = type
+ self.language = language
+ self.locale = locale
+ }
+}

Sources/Snowplow/Ecommerce/Entities/EcommerceUserEntity.swift

@@ -0,0 +1,71 @@
+// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License
+// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at
+// http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on
+// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+// express or implied. See the Apache License Version 2.0 for the specific
+// language governing permissions and limitations there under.
+
+import Foundation
+
+/**
+ Attach Ecommerce User details to events. It is designed to help in modeling guest/non-guest account activity.
+ Entity schema: `iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0`
+ */
+@objc(SPEcommerceUserEntity)
+public class EcommerceUserEntity: NSObject {
+ /// The user ID.
+ @objc
+ public var id: String
+
+ /// Whether or not the user is a guest.
+ public var isGuest: Bool?
+
+ /// The user's email address.
+ @objc
+ public var email: String?
+
+ internal var entity: SelfDescribingJson {
+ var data: [String : Any] = ["id": id]
+ if let isGuest = isGuest { data["is_guest"] = isGuest }
+ if let email = email { data["email"] = email }
+
+ return SelfDescribingJson(schema: ecommerceUserSchema, andData: data)
+ }
+
+ /// - Parameter id: The user ID.
+ /// - Parameter isGuest: Whether or not the user is a guest.
+ /// - Parameter email: The user's email address.
+ public init(
+ id: String,
+ isGuest: Bool? = nil,
+ email: String? = nil
+ ) {
+ self.id = id
+ self.isGuest = isGuest
+ self.email = email
+ }
+
+ /// - Parameter id: The user ID.
+ /// - Parameter email: The user's email address.
+ @objc
+ public init(
+ id: String,
+ email: String? = nil
+ ) {
+ self.id = id
+ self.email = email
+ }
+
+ /// Whether or not the user is a guest.
+ @objc
+ public func isGuest(_ isGuest: Bool) -> Self {
+ self.isGuest = isGuest
+ return self
+ }
+}