VisilabsIOS 4.3.4

VisilabsIOS 4.3.4

×

由 Related Digital 维护。

VisilabsIOS 4.3.4

  • 由
  • Related Digital

IVisilabs Logo

Actions Status Version License Platform SPM compatible

目录

介绍

这个库是 Visilabs 为原生 IOS 项目提供的官方 Swift SDK。该库用 Swift 5 编写，最低部署目标版本是 10。

如果您使用的是 Swift 的较低版本，或者您的项目的最小部署目标版本低于 10，我们建议使用 Objective-C 库。

示例

要运行示例项目，克隆仓库，然后在示例目录中运行 pod install

安装

VisilabsIOS 可通过 CocoaPods 获取。要安装它，只需将以下行添加到您的 Podfile 中。

pod 'VisilabsIOS'

使用方法

初始化

在 AppDelegate.swift 中导入 VisilabsIOS 并在 application:didFinishLaunchingWithOptions: 方法中调用 createAPI 方法。

以下代码是 Visilabs 库初始化的示例。

import VisilabsIOS

func application(_ application: UIApplication, didFinishLaunchingWithOptions 
        launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Visilabs.createAPI(organizationId: "YOUR_ORGANIZATION_ID", profileId: "YOUR_PROFILE_ID"
        , dataSource: "YOUR_DATASOURCE", inAppNotificationsEnabled: false, channel: "IOS"
        , requestTimeoutInSeconds: 30, geofenceEnabled: false, maxGeofenceCount: 20, isIDFAEnabled: true)
        return true
    }

初始化参数

  • 必填参数
  • 可选参数
    • inAppNotificationsEnabled：默认值是false。如果您想使用Visilabs的内置应用通知功能，需要将此值设置为true。如果您不使用Visilabs的内置应用通知功能，出于性能考虑，建议保持此值为false，因为每次事件请求都会发送另一个请求来检查是否存在相关的通知。
    • channel：默认值是"IOS"。如果您想在管理员面板的Analytics部分将您的iOS应用的事件分类到另一个不同的通道名称下，您可以更改此值。
    • requestTimeoutInSeconds：默认值是30。向Visilabs服务器发送数据并接收数据请求的超时时间，单位为秒。
    • geofenceEnabled：默认值是false。如果您想使用Visilabs的地理围栏功能，需要将此值设置为true。如果您不使用Visilabs的地理围栏功能，出于性能和用户体验考虑，建议保持此值为false，因为区域监控会增加您应用程序的电池消耗，并弹出对话框让用户允许定位跟踪。
    • maxGeofenceCount：默认值是20。Apple防止任何单个应用程序同时监控超过20个区域。Visilabs可以使用所有这些空间。但是，如果您需要将这些空间中的某些空间用于其他用途，可以将此参数设置为小于20的值。设置大于20的值不会影响要监控的最大区域数。
    • isIDFAEnabled：默认值是true。iOS 14之后，如果您想使用AdvertisingTrackingID，您应从终端用户请求权限。如果此参数为true，则应将NSUserTrackingUsageDescription键添加到您的Info.plist文件中，并添加适当的描述。当调用了createAPI后，将打开对一个终端用户的请求权限的对话框，并根据用户的选项，将AdvertisingTrackingID的值发送到Visilabs服务器。如果您希望在其他时间显示提示而不是打开应用程序时，需要将isIDFAEnabled的值设置为false，并在任何时候需要显示提示时调用公开的requestIDFA函数。点击这里获取详细信息

Image of Profiles

Image of Profile

调试

您可以通过将loggingEnabled属性设置为true来开启日志记录。如果启用

Visilabs.callAPI().loggingEnabled = true

请求Visilabs服务器的默认协议是https。如果您想更轻松地调试请求，您可以将协议更改为由将insecureProtocol属性设置为true。

Visilabs.callAPI().insecureProtocol = true

数据收集

Vislabs 使用事件来从 iOS 应用程序收集数据。开发者需要实现 SDK 提供的方法。《code>customEvent 是一个通用方法来跟踪用户事件。《code>customEvent 接收 2 个参数：页面名和属性。

  • 页面名：您的应用程序当前页面。如果您的事件与页面浏览无关，则应传递与事件相关的值。如果传递空 String，事件将被视为无效并丢弃。
  • 属性：与事件相关的键/值对集合。如果您的事件没有除页面名之外的其他数据，传递空字典是可以的。

在 SDK 中，除了 customEvent，还有两个其他方法用于收集数据：login 和 signUp。与 customEvent 方法一样，login 和 signUp 方法也包含一个必填参数和一个可选参数。第一个参数是 exVisitorId，它唯一标识用户且不能为空。第二个参数 properties 是可选的，传递空字典也是有效的。

一些最常见的事件

注册

Visilabs.callAPI().signUp(exVisitorId: "userId")

此外，您还可以在用户注册时通过可选参数 properties 传递额外的信息。以下示例显示了使用包含 OM.sys.TokenID 和 OM.sys.AppID 参数属性的《code>signUp 方法的调用。OM.sys.TokenID 和 OM.sys.AppID 参数是发送推送通知必需的，可通过 RMC 网页面板获取 OM.sys.AppID 参数。

var properties = [String:String]()
properties["OM.sys.TokenID"] = "F7C5231053E6EC543B8930FB440752E2FE41B2CFC2AA8F4E9C4843D347E6A847" // Token ID to use for push messages
properties["OM.sys.AppID"] = "VisilabsIOSExample" //App ID to use for push messages
Visilabs.callAPI().signUp(exVisitorId: "userId", properties: properties)

登录

与 《code>signUp 方法一样，《code>login 方法可以带有或没有可选参数 properties。

Visilabs.callAPI().login(exVisitorId: "userId")
var properties = [String:String]()
properties["OM.sys.TokenID"] = "F7C5231053E6EC543B8930FB440752E2FE41B2CFC2AA8F4E9C4843D347E6A847" // Token ID to use for push messages
properties["OM.sys.AppID"] = "VisilabsIOSExample" //App ID to use for push messages
Visilabs.callAPI().login(exVisitorId: "userId", properties: properties)

此外，您还可以将用户细分参数添加到 properties 中。

var properties = [String:String]()
properties["OM.vseg1"] = "seg1val" // Visitor Segment 1
properties["OM.vseg2"] = "seg2val" // Visitor Segment 2
properties["OM.vseg3"] = "seg3val" // Visitor Segment 3
properties["OM.vseg4"] = "seg4val" // Visitor Segment 4
properties["OM.vseg5"] = "seg5val" // Visitor Segment 5
properties["OM.bd"] = "1977-03-15" // Birthday
properties["OM.gn"] = "f" // Gender
properties["OM.loc"] = "Bursa" // Location
Visilabs.callAPI().login(exVisitorId: "userId", properties: properties)

页面查看

使用以下实现的 customEvent 方法来记录访客当前正在查看的页面名称。您可以在属性字典中添加额外的参数，或者将其留空。

Visilabs.callAPI().customEvent("Frequently Asked Questions" /*Page Name*/, properties: [String:String]())

商品查看

当用户在移动应用程序中展示商品时，使用以下 customEvent 的实现。

var properties = [String:String]()
properties["OM.pv"] = "12345" // Product Code
properties["OM.pn"] = "USB Charger" // Product Name
properties["OM.ppr"] = 125.49" // Product Price
properties["OM.pv.1"] = "Sample Brand" // Product Brand
properties["OM.inv"] = "5" // Number of items in stock
Visilabs.callAPI().customEvent("Product View", properties: properties)

添加到购物车

当用户将商品添加到购物车或移除时，使用以下 customEvent 的实现。

var properties = [String:String]()
properties["OM.pbid"] = "bid-12345678" // Basket ID
properties["OM.pb"] = "12345;23456" // Product1 Code;Product2 Code
properties["OM.pu"] = "3;1" // Product1 Quantity;Product2 Quantity
properties["OM.ppr"] = "376.47;23.50" // Product1 Price*Product1 Quantity;Product2 Price*Product2 Quantity
Visilabs.callAPI().customEvent("Cart", properties: properties)

商品购买

当用户购买一个或多个项目时，使用以下 customEvent 的实现。

var properties = [String:String]()
properties["OM.tid"] = "oid-12345678" // Order ID/Transaction ID
properties["OM.pp"] = "12345;23456" // Product1 Code;Product2 Code
properties["OM.pu"] = "3;1" // Product1 Quantity;Product2 Quantity
properties["OM.ppr"] = "376.47;23.50" // Product1 Price*Product1 Quantity;Product2 Price*Product2 Quantity
Visilabs.callAPI().customEvent("Purchase", properties: properties)

商品分类页面查看

用户查看分类列表页面时，使用以下 customEvent 的实现。

var properties = [String:String]()
properties["OM.clist"] = "c-14" // Category Code/Category ID
Visilabs.callAPI().customEvent("Category View", properties: properties)

应用内搜索

如果移动应用中提供搜索功能，可以使用以下customEvent的实现。

var properties = [String:String]()
properties["OM.OSS"] = "USB" // Search Keyword
properties["OM.OSSR"] = "61" // Number of Search Results
Visilabs.callAPI().customEvent("In App Search", properties: properties)

横幅点击

您可以使用以下customEvent实现来监控横幅点击数据。

var properties = [String:String]()
properties["OM.OSB"] = "b-666" // Banner Name/Banner Code
Visilabs.callAPI().customEvent("Banner Click", properties: properties)

添加到收藏

当用户将产品添加到收藏夹时，请使用以下customEvent的实现。

var properties = [String:String]()
properties["OM.pf"] = "12345" // Product Code
properties["OM.pfu"] = "1"
properties["OM.ppr"] = 125.49" // Product Price
Visilabs.callAPI().customEvent("Add To Favorites", properties: properties)

从收藏中删除

当用户从收藏中删除产品时，请使用以下customEvent的实现。

var properties = [String:String]()
properties["OM.pf"] = "12345" // Product Code
properties["OM.pfu"] = "-1"
properties["OM.ppr"] = 125.49" // Product Price
Visilabs.callAPI().customEvent("Add To Favorites", properties: properties)

发送活动参数

在点击推送消息启动应用程序后，请使用以下对 customEvent 的实现。

var properties = [String:String]()
properties["utm_source"] = "euromsg" // utm_source value in the payload of push notification
properties["utm_medium"] = "push" // utm_medium value in the payload of push notification
properties["utm_campaign"] = "euromsg campaign" // utm_campaign value in the payload of push notification
Visilabs.callAPI().customEvent("Login", properties: properties)

您还可以发送属性而无需设置页面名称。

var properties = [String:String]()
properties["utm_source"] = "euromsg" // utm_source value in the payload of push notification
properties["utm_medium"] = "push" // utm_medium value in the payload of push notification
properties["utm_campaign"] = "euromsg campaign" // utm_campaign value in the payload of push notification
Visilabs.callAPI().sendCampaignParameters(properties: properties)

推送消息令牌注册

Visilabs 需要接收令牌才能向用户发送推送消息。APNS 生成的令牌值将是 OM.sys.TokenID 键的值。可以通过 RMC 管理面板获取 OM.sys.AppID 的值。请按照以下链接https://intelligence.relateddigital.com/a02/index#/Push/AppList选择相关的推送应用程序。App Alias 的值是指 OM.sys.AppID。如果您遇到问题，请联系 RMC 支持团队。

var properties = [String:String]()
properties["OM.sys.TokenID"] = "F7C5231053E6EC543B8930FB440752E2FE41B2CFC2AA8F4E9C4843D347E6A847" // Token ID to use for push messages
properties["OM.sys.AppID"] = "VisilabsIOSExample" //App ID to use for push messages
Visilabs.callAPI().customEvent("RegisterToken", properties: properties)

IOS Application Page

请求并发送 IDFA

您可以在任何时候调用 requestIDFA 函数以显示请求 IDFA 的 应用跟踪透明度 提示，并将值发送到 Visilabs 服务器。

Visilabs.callAPI().requestIDFA()

发送位置状态信息

您可以通过调用 sendLocationPermission 方法将用户的地理位置权限状态发送到 Visilabs 服务器，并在以后的控制面板中使用这些信息。

Visilabs.callAPI().sendLocationPermission()

该信息将与 OM.locpermit 参数一起发送，可以取以下三个值之一

  • "always" : 地理位置权限在任何时候都获得，无论应用是打开还是关闭。
  • "appopen" : 只有当应用打开时才获得地理位置权限。
  • "none" : 没有获得地理位置权限。

定位操作

内联消息

内联消息是在用户直接在您的移动应用中活动时向您用户显示的通知。要启用内联消息功能，您需要在调用createAPI以初始化SDK时设置inAppNotificationsEnabled参数的值。

import VisilabsIOS

func application(_ application: UIApplication, didFinishLaunchingWithOptions 
        launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Visilabs.createAPI(organizationId: "YOUR_ORGANIZATION_ID", profileId: "YOUR_PROFILE_ID"
        , dataSource: "YOUR_DATASOURCE", inAppNotificationsEnabled: true, channel: "IOS"
        , requestTimeoutInSeconds: 30, geofenceEnabled: false, maxGeofenceCount: 20)
        return true
    }

每个由customEvent调用控制的活动的相关< strong>内联消息的存在。您可以在RMC管理面板的https://intelligence.relateddigital.com/#Target/TargetingAction/TAList页面上创建和自定义您的< strong>内联消息。

共有9种类型的< strong>内联消息

弹出窗口 - 图片、标题、文本和按钮 迷你图标和文本 全屏图像
full mini full_image
全屏图像和按钮 弹出窗口 - 图片、标题、文本和按钮 弹出窗口-调查
image_button image_text_button smile_rating
弹出窗口 - NPS带文本和按钮 本地警报和操作表 NPS带数字
nps nps_with_numbers nps_with_numbers

如果您想自己管理为内联消息添加的链接，可以按照以下步骤操作。

首先，您必须调用代表方法

Visilabs.callAPI().inappButtonDelegate = self

然后，您必须添加扩展，您可删除打印代码并编写自己的代码。

extension EventViewController: VisilabsInappButtonDelegate {
    func didTapButton(_ notification: VisilabsInAppNotification) {
        print("notification did tapped...")
        print(notification)
    }
}

喜爱的属性操作

您可以通过以下方式通过移动应用程序访问您在https://intelligence.relateddigital.com/#Target/TargetingAction/TAList/部分定义的喜爱属性操作类型的< strong>定位操作的喜爱属性。

Visilabs.callAPI().getFavoriteAttributeActions { (response) in
    if let error = response.error {
        print(error)
    } else {
        if let favoriteBrands = response.favorites[.brand] {
            for brand in favoriteBrands {
                print(brand)
            }
        }
        if let favoriteCategories = response.favorites[.category] {
            for category in favoriteCategories {
                print(category)
            }
        }
    }
}

您还可以通过指定< strong>ID来访问特定< strong>定位操作的喜爱属性。

Favorite Attribute Action

Visilabs.callAPI().getFavoriteAttributeActions(actionId: 188) { (response) in
    if let error = response.error {
        print(error)
    } else {
        if let favoriteBrands = response.favorites[.brand] {
            for brand in favoriteBrands {
                print(brand)
            }
        }
        if let favoriteCategories = response.favorites[.category] {
            for category in favoriteCategories {
                print(category)
            }
        }
    }
}

response 对象的 favorites 属性是一个字典，其键为一个 enum 类型，值为一个 String 的数组。以下为 VisilabsFavoriteAttribute enum 的案例：

public enum VisilabsFavoriteAttribute: String {
    case ageGroup
    case attr1
    case attr2
    case attr3
    case attr4
    case attr5
    case attr6
    case attr7
    case attr8
    case attr9
    case attr10
    case brand
    case category
    case color
    case gender
    case material
    case title
}

Story Actions

故事操作允许您在 iOS 设备上添加类似于 "Instagram Story" 列表视图的小部件。 getStoryView 方法返回一个 VisilabsStoryHomeView 的实例，它是 UIView 的子类。

let storyView = Visilabs.callAPI().getStoryView()
view.addSubview(storyHomeView)

您也可以通过指定 Targeting Action 的 ID 来访问故事操作。

let storyView = Visilabs.callAPI().getStoryView(actionId: 67)
view.addSubview(storyHomeView)

如果您添加一个可点击的 URL，框架会将其在浏览器中打开（或通过深度链接直接打开）。但是，如果您想自行处理，需要扩展一个符合 VisilabsStoryURLDelegate 的类，如下所示：

extension StoryViewController: VisilabsStoryURLDelegate {
    func urlClicked(_ url: URL) {
        //TO DO
    }
}

添加后，您可以将 urlDelegate 设置为 self。

let storyView = Visilabs.callAPI().getStoryView(actionId: 67, urlDelegate: self)
view.addSubview(storyHomeView)

如果您设置了代理，则可点击的 URL 不会由 SDK 处理！

还有 getStoryView 方法的异步版本，称为 getStoryViewAsync，它接收一个 completionHandler，该 completionHandler 接收一个可选的 VisilabsStoryHomeView 对象。如果没有找到符合您标准的故事操作，completionHandler 返回 nil。

Visilabs.callAPI().getStoryViewAsync(actionId: 55){ storyHomeView in
    if let storyHomeView = storyHomeView {
        
    } else {
        print("There is no story action matching your criteria.")
    }
}

地理围栏

要启用您的应用程序的位置服务，首先需要将以下键添加到您的 Info.plist 文件中。

  • NSLocationAlwaysAndWhenInUseUsageDescription
  • NSLocationWhenInUseUsageDescription

以下是一个示例，演示如何实现这些权限：

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need access to your location for better user experience.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location for better user experience.</string>

您还需要在您的 Info.plist 文件中的 UIBackgroundModes 下方添加以下键，以监视区域、刷新区域列表和接收推送通知。

<array>
    <string>fetch</string>
    <string>location</string>
    <string>remote-notification</string>
</array>

初始化 Visilabs SDK 时，您需要将 createAPI 方法的 geofenceEnabled 参数设置为 true。您还可以将 maxGeofenceCount 更改为小于 20 的值。 Apple 阻止任何单一应用程序同时监控超过 20 个区域。Visilabs 可以使用所有这些插槽。

import VisilabsIOS

func application(_ application: UIApplication, didFinishLaunchingWithOptions 
        launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Visilabs.createAPI(organizationId: "YOUR_ORGANIZATION_ID", profileId: "YOUR_PROFILE_ID"
        , dataSource: "YOUR_DATASOURCE", inAppNotificationsEnabled: false, channel: "IOS"
        , requestTimeoutInSeconds: 30, geofenceEnabled: true, maxGeofenceCount: 20)
        return true
    }

邮件订阅表单

在 RMC 控面板创建表单后，与应用内消息类似，邮件订阅表单的存在性由每次 customEvent 调用后控制。如下所示；

mail-subscription-form

赢取大奖

在 RMC 控面板创建表单后，与应用内消息类似，赢取大奖的存在性由每次 customEvent 调用后控制。它将打开一个 WebViewController。如下所示；

赢取大奖完整版 赢取大奖半版
spin-to-win-full spin-to-win-half

内嵌Nps计分板

要显示带有数字的内嵌Nps视图，可以调用 getNpsWithNumbersView 方法，该方法接收一个类型为 [String: String] 的 properties 参数，包含触发用户点击按钮时被调用的 npsItemClicked 方法的 delegate 参数，以及接收一个可选的 VisilabsNpsWithNumbersContainerView 对象的 completionHandler。

delegate 参数用于处理按钮点击事件，并包含一个当用户点击按钮时被触发的方法 npsItemClicked。

completionHandler 接收一个可选的 VisilabsNpsWithNumbersContainerView 对象，该对象仅在存在匹配给定标准的行为时返回。如果没有匹配的行为，则 completionHandler 将返回 nil。

Visilabs.callAPI().getNpsWithNumbersView(properties: props, delegate: self){ npsView in
    DispatchQueue.main.async {
        if let npsView = npsView {
            self.npsView = npsView
            self.npsView = npsView
            self.view.addSubview(npsView)
            npsView.translatesAutoresizingMaskIntoConstraints = false
            npsView.topAnchor.constraint(equalTo: self.npsWithNumbersButton.bottomAnchor, constant: -50).isActive = true
            npsView.widthAnchor.constraint(equalTo: self.view.saferAreaLayoutGuide.widthAnchor).isActive = true
            npsView.heightAnchor.constraint(equalToConstant: 550).isActive = true
        } else {
            print("There is no nps action matching your criteria.")
        }
    }
}
extension NpsViewController: VisilabsNpsWithNumbersDelegate {
    func npsItemClicked(npsLink: String?) {
        print(npsLink)
    }
}

推荐

产品推荐由 SDK 的 recommend 方法处理。您需要向 recommend 方法传递 3 个必填参数，分别是 zoneId、productCode 和 completion。

completion 参数是一个闭包表达式，它接受一个 VisilabsRecommendationResponse 实例作为输入并返回空值。下面是 VisilabsRecommendationResponse 的结构

public class VisilabsRecommendationResponse {
    public var products: [VisilabsProduct]
    public var error: VisilabsError?
    public var widgetTitle: String = ""
    
    internal init(products: [VisilabsProduct], widgetTitle: String = "", error: VisilabsError? = nil) {
        self.products = products
        self.widgetTitle = widgetTitle
        self.error = error
    }
}

VisilabsProduct 类具有以下属性

属性 类型
code String
title String
img String
dest_url String
brand String
price Double
dprice Double
cur String
dcur String
freeshipping Bool
samedayshipping Bool
rating Int
comment Int
discount Double
attr1 String
attr2 String
attr3 String
attr4 String
attr5 String

如果 completion 方法中存在给定的参数的推荐产品，您需要处理产品数组。

Visilabs.callAPI().recommend(zoneID: "6", productCode: "pc", filters: []){ response in
    if let error = response.error {
        print(error)
    }else{
        print("Recommended Products")
        for product in response.products{
            print("product code: \(product.code) title: \(product.title)")
        }
    }
}

您还可以向 recommend 方法传递一个筛选器数组。例如，以下实现仅返回标题中包含 laptop 的产品。

var filters = [VisilabsRecommendationFilter]()
let filter = VisilabsRecommendationFilter(attribute: .PRODUCTNAME, filterType: .like, value: "laptop")
filters.append(filter)
Visilabs.callAPI().recommend(zoneID: "6", productCode: "pc", filters: filters){ response in
    if let error = response.error{
        print(error)
    }else{
        print("Widget Title: \(response.widgetTitle)")
        print("Recommended Products")
        for product in response.products{
            print("product code: \(product.code) title: \(product.title)")
        }
    }
}

VisilabsProductFilterAttribute 枚举有以下情况及示例值

情况 示例
PRODUCTCODE ""
PRODUCTNAME ""
COLOR "blue"
AGEGROUP "18-40"
BRAND "visilabs"
CATEGORY "145"
GENDER "f"
MATERIAL "wood"
ATTRIBUTE1 "attr1value"
ATTRIBUTE2 "attr2value"
ATTRIBUTE3 "attr3value"
ATTRIBUTE4 "attr4value"
ATTRIBUTE5 "attr5value"
SHIPPINGONSAMEDAY "1"
FREESHIPPING "1"
ISDISCOUNTED "1"

报告推荐点击

要报告小部件推荐的点击次数，您需要使用 Product 对象的 qs 属性调用 trackRecommendationClick 方法。

Visilabs.callAPI().trackRecommendationClick(qs: product.qs)

作者

[[email protected]]