ViSearch Swift SDK 和 Demo 源代码

1. 概述

本SDK包含两套API，提供准确、可靠和可扩展的搜索。它是一个开源软件，可以轻松集成ViSearch API和ProductSearch API到您的iOS应用程序中。下表提供了更多关于API的具体信息。

API	描述
ViSearch	基于ViSearch解决方案API，提供四种搜索方法：查找相似、你可能还喜欢、按图片搜索和按颜色搜索。更多详情请参阅ViSearch API文档。
ProductSearch	ViSenze Discovery Suite通过帮助他们更轻松地搜索、浏览和与产品互动，为您的客户提供更好的和更直观的产品搜索和发现体验。ProductSearch API提供了一套新的基于产品的API，与ViSenze目录管理器协同工作。在SDK中，ProductSearch API被称为`ViProductSearch`。

请访问Github仓库获取源代码和参考。

当前稳定版本：1.10.3（Swift 5+）

支持的iOS版本：iOS 8.x及以上

2. 设置

2.1 设置Xcode项目

在Xcode中，选择 File > New > Project，然后选择 Single View Application。

输入您的项目名称并按 Next，这里我们使用 Demo 作为项目名称。

2.2 导入 ViSearch Swift SDK

2.2.1 使用 CocoaPods

首先您需要安装 CocoaPods Ruby gem

# Xcode 7 + 8
sudo gem install cocoapods --pre

然后进入您的项目文件夹，创建一个空的 Podfile

cd /path/to/Demo
pod init

按照以下方式编辑 Podfile。请更新到最新版本。这里仅作为参考。

platform :ios, '12.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'ViSearchSDK', '~>1.10.3'
end
...

安装 ViSearch SDK

pod install

应该会创建 Demo.xcworkspace 项目。

2.2.2 使用 Carthage

在您的 project.pbxproj 或 .xcworkspace 文件相同目录中创建一个 Cartfile。
按照以下方式列出依赖：github "visenze/visearch-sdk-swift" ~> 1.10.3。请更改为最新的可用版本。
运行 carthage update --use-xcframeworks 或 carthage bootstrap --platform iOS --cache-builds --no-use-binaries --use-xcframeworks。由于 ViSenzeAnalytics.xcframework 没有拉取，它是一个依赖项，我们将在下一步解决它。
在您的 .xcodeproj 或 .xcworkspace 文件相同目录下将出现一个 Cartfile.resolved 文件和一个 Carthage 目录。
导航至 ViSearchSDK 文件夹：cd Carthage/Checkouts/visearch-sdk-swift/ViSearchSDK，它包含 ViSearchSDK 的源代码。
再次运行 carthage update --use-xcframeworks 或 carthage bootstrap --platform iOS --cache-builds --no-use-binaries --use-xcframeworks。这将拉取和构建 Analytics 依赖项。
返回到您的与应用程序 project.pbxproj 或 .xcworkspace 文件相同的根目录。
再次运行 carthage 命令（与第 3 步相同）。
构建将成功。
将生成的 ViSearchSDK.xcframework 或 ViSenzeAnalytics.framework 包从 Carthage/Build 拖到您应用程序 Xcode 项目的“框架和库”部分。
如果您在应用程序中使用 Carthage，请选择“嵌入并签名”，否则选择“不嵌入”。

2.2.3 使用手动方法

您还可以直接下载iOS ViSearch SDK。使用时，解压它，并将ViSearchSDK项目（位于ViSearchSDK文件夹中）拖动到您的项目中。ViSearchSDK项目生成ViSearchSDK框架，并且有一个依赖关系，即ViSenzeAnalytics。在可以使用之前，您需要运行并拉取ViSenzeAnalytics框架，方法是在终端运行

carthage update --use-xcframeworks

要验证ViSearchSDK项目能否成功编译，打开ViSearchSDK.xcodeproj，确保它可以成功构建并且ViSenzeAnalytics框架位于“框架和库”下。如果由于某种原因，丢失了框架，您还可以在ViSearchSDK/Carthage/Build/ViSenzeAnalytics.xcframework路径下找到它。如果缺少框架，您可以手动将其添加到项目中。

之后，您可以将ViSearchSDK文件夹复制到您的项目中。

打开ViSearchSDK文件夹，并将其中的ViSearchSDK.xcodeproj拖到您的应用程序的Xcode项目的Project Navigator中。

它应该出现在您应用程序蓝色项目图标下面。它是在所有其他Xcode组之上还是之下无关紧要。
在Project Navigator中选中ViSearchSDK.xcodeproj，并验证部署目标与您的应用程序目标一致。
接下来，在Project Navigator中（蓝色项目图标）选择您的应用程序项目，进入目标配置窗口，然后在侧边栏的“目标”下选择应用程序目标。
在该窗口顶部的标签栏中，打开“通用”面板。
在“已嵌入的二进制文件”部分下点击+按钮。
选择ViSearchSDK.framework。

ViSearchSDK.framework将以目标依赖项、链接框架和嵌入框架的形式自动添加。

您已完成操作！

2.3 添加隐私用途描述

iOS 10现在要求用户允许访问相机和照片库。如果您的应用程序需要这些访问，请在Info.plist中添加NSCameraUsageDescription和NSPhotoLibraryUsageDescription的描述。更多详细信息请参阅此处。

3. 初始化

3.1 ViSearch

ViSearch 必须在可以使用之前使用 appKey 或 accessKey/secretKey 对进行初始化。

import ViSearchSDK
...
// using default ViSearch client. The client, by default, will connect to Visenze's server

// recommended way of init ViSearch client with app key
ViSearch.sharedInstance.setup(appKey: "YOUR_APP_KEY")

// old way of init ViSearch client with access and secret key pair
ViSearch.sharedInstance.setup(accessKey: "YOUR_ACCESS_KEY", secret: "YOUR_SECRET_KEY")

...
// or using customized client, which connects to your own server
client = ViSearchClient(baseUrl: yourUrl, accessKey: accessKey, secret: secret)
...

如果您连接到其他端点而非默认端点（https://visearch.visenze.com），请以此方式初始化 ViSearch 客户端。

client = ViSearchClient(baseUrl: "https://custom-visearch.yourdomain.com", accessKey: accessKey, secret: secret)

对于在中国地区的搜索，请将端点更改为 https://visearch.visenze.com.cn。

默认情况下，API 搜索请求将在 10 秒后超时。要更改超时时间，您可以使用以下方式配置客户端。

            
// configure timeout to 30s example. By default timeout is set 10s.
ViSearch.sharedInstance.client?.timeoutInterval = 30
ViSearch.sharedInstance.client?.sessionConfig.timeoutIntervalForRequest = 30
ViSearch.sharedInstance.client?.sessionConfig.timeoutIntervalForResource = 30
ViSearch.sharedInstance.client?.session = URLSession(configuration: (ViSearch.sharedInstance.client?.sessionConfig)!)

3.2 产品搜索

ProductSearch 必须在使用之前使用 appKey 和 placementId 进行初始化。

对于在中国地区的搜索，请设置 base_url 为 https://search.visenze.com.cn。对于分析，您将使用 forCn 设置为 true 进行追踪器初始化。

import ViSearchSDK

// initialize ProductSearch API using app key and placement id
ViProductSearch.sharedInstance.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID)

// custom search endpoint
ViProductSearch.sharedInstance.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID, baseUrl:"https://custom-search.yourdomain.com")

// configure timeout to 30s example. By default timeout is set 10s.
ViProductSearch.sharedInstance.client?.timeoutInterval = 30
ViProductSearch.sharedInstance.client?.sessionConfig.timeoutIntervalForRequest = 30
ViProductSearch.sharedInstance.client?.sessionConfig.timeoutIntervalForResource = 30
ViProductSearch.sharedInstance.client?.session = URLSession(configuration: (ViProductSearch.sharedInstance.client?.sessionConfig)!)

3.2.1 多放置的设置

如果您想创建多个 ProductSearch 实例，您可以多次实例化 ViProductSearch。

var placement111 = ViProductSearch()
placement111.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID)

var placement222 = ViProductSearch()
placement222.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID)

4. 解决方案API

4.1 ViSearch

4.1.1 形似推荐

GET /search

形似推荐 解决方案用于通过提供索引图像的唯一标识符（im_name），在图像数据库中搜索视觉上相似的图像。

import ViSearchSDK

...
let params = ViSearchParams(imName: "imName-example")
ViSearch.sharedInstance.findSimilar( params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                            // Do something when request succeeds
                            // preview by calling : dump(data)
                            // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                   failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
                    })

...

4.1.2 通过图像搜索

POST /uploadsearch

通过图像搜索 解决方案用于通过上传图像或提供图像URL来搜索相似的图像。您应该构建 UIImage 对象并将其传递给 ViUploadSearchParams 来开始搜索。

使用图像

import ViSearchSDK
...

let image = UIImage(named: "someImage.png")
let params = ViUploadSearchParams(image: image!)

ViSearch.sharedInstance.uploadSearch(params: params,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
					})

或者，您可以直接将图像URL传递给 ViUploadSearchParams 来开始搜索

import ViSearchSDK
...

let params = ViUploadSearchParams(im_url: "http://somesite.com/sample_image.png")
        
ViSearch.sharedInstance.uploadSearch(params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
                    })
...

上传图像后，您将收到来自搜索结果的 im_id 属性。如果您想再次搜索相同的图像，您可以通过指定参数中的 im_id 来节省带宽

import ViSearchSDK
...

let params = ViUploadSearchParams(im_id: "im_id_example")
        
ViSearch.sharedInstance.uploadSearch(params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")


...

4.1.2.1 选择框

如果您想要搜索的对象仅占据图片的一小部分，或者同一图片中存在其他无关对象，那么搜索结果可能会不准确。使用框参数可以调整搜索区域，以提高准确性。框坐标以上传图片的原始尺寸为准。注意：坐标系使用像素为单位，而不是点。

// create the box to refine the area on the searching image
// ViBox(x1, y1, x2, y2) where (0,0) is the top-left corner
// of the image, (x1, y1) is the top-left corner of the box,
// and (x2, y2) is the bottom-right corner of the box.
...

let params = ViUploadSearchParams(.....)

let box = ViBox(x1: 0, y1: 0, x2: 100, y2: 100)
params!.box = box
        
// start searching
...

4.1.2.2 缩放设置

在执行上传搜索时，您可能会注意到随着图像文件大小的增加，搜索延迟也会增加。这是因为将图像发送到ViSearch服务器所需的时间增加，以及ViSearch处理大图像文件所需的时间增加。

为了减少上传搜索延迟，默认情况下，uploadSearch方法会创建您的图像文件的副本，并将副本的大小调整到512x512像素，如果原始尺寸的任何一个超过512像素。这是降低搜索延迟的同时，又不牺牲通用场景搜索准确性的优化大小。

// by default, the max width of the image is set to 512px, quality is 0.97
let params = ViUploadSearchParams(.....)

// or you can explicitly set a param's settings
params?.img_settings = ViImageSettings(setting: .highQualitySetting)

如果您的图像包含诸如纺织品图案和纹理等细小细节，您可以使用更大尺寸的图像进行搜索以获得更好的搜索结果

// by default, the max width of the image is set to 512px, quality is 0.97
let params = ViUploadSearchParams(.....)

// set the image with high quality settings.
// Max width is 1024px, and the quality is 0.985. Note: Quality with 1.0 take hugespace
params?.img_settings = ViImageSettings(setting: .highQualitySetting)

或者，提供自定义调整大小设置。为了有效地利用移动设备的内存和网络带宽，最大大小设置为1024 x 1024。任何超过限制的图像将被调整到该限制。

//resize the image to 800 by 800 area using jpeg 0.9 quality
params?.img_settings = ViImageSettings(size: CGSize(width: 800, height: 800), quality: 0.9)

4.1.3 通过颜色搜索

GET /colorsearch

通过颜色搜索方法通过提供一个颜色代码来搜索类似颜色的图像。颜色代码应为十六进制格式，并以字符串形式传递到ViColorSearchParams。

import ViSearchSDK
...

let params = ViColorSearchParams(color: "ff00ff")
// alternately, you can pass UIColor object to the initializer
// let params = ViColorSearchParams(color: someUIColorObject)

client.colorSearch( params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                        },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \(err.localizedDescription)")
					})

...

4.1.4 多产品搜索

POST /discoversearch

多产品搜索解决方案可以通过上传图片或提供图片URL来搜索相似图像，类似于图片搜索。多产品搜索能够检测图像中的所有对象，并一次性返回每个对象的相似图像。

使用图像

import ViSearchSDK
...

let image = UIImage(named: "someImage.png")
let params = ViUploadSearchParams(image: image!)

ViSearch.sharedInstance.discoverSearch(params: params,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
					})

或者，您可以直接将图像URL传递给 ViUploadSearchParams 来开始搜索

import ViSearchSDK
...

let params = ViUploadSearchParams(im_url: "http://somesite.com/sample_image.png")
        
ViSearch.sharedInstance.discoverSearch(params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
                    })
...

上传图像后，您将收到来自搜索结果的 im_id 属性。如果您想再次搜索相同的图像，您可以通过指定参数中的 im_id 来节省带宽

import ViSearchSDK
...

let params = ViUploadSearchParams(im_id: "im_id_example")
        
ViSearch.sharedInstance.discoverSearch(params: params!,
                    successHandler: {
                        (data : ViResponseData?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")


...

4.2 ProductSearch

4.2.1 图片搜索

POST /v1/product/search_by_image

可以通过3个不同的参数进行图片搜索 - 图片URL、图片ID、图片文件。

使用图片URL

import ViSearchSDK
...
let params = ViSearchByImageParam(imUrl: "IMAGE_URL")

使用图片ID（ID可以从之前的搜索响应中获取）

import ViSearchSDK
...
let params = ViSearchByImageParam(im_id: "IMAGE_ID")

使用图片文件（UIImage）

import ViSearchSDK
...
let params = ViSearchByImageParam(image: UIImage(contentsOfFile: "IMAGE_FILEPATH"))

启动搜索

ViProductSearch.sharedInstance.searchByImage(
    params: params,
    successHandler: { 
        (response: ViProductSearchResponse?) -> Void in
        // your function to process response
    },
    failureHandler: {
        (err: Error) -> Void in 
        // your function to handle error
    }
)

4.2.2 推荐

GET /v1/product/recommendations/{product-id}

import ViSearchSDK
...
let params = ViSearchByIdParam(productId: "PRODUCT_ID")

ViProductSearch.sharedInstance.searchById(
    successHandler: { 
        (response: ViProductSearchResponse?) -> Void in
        // your function to process response
    },
    failureHandler: {
        (err: Error) -> Void in 
        // your function to handle error
    }
)

5. 搜索结果

ViSearch 和 ProductSearch 各自都有相应的响应，但它们有很多相似之处，更详细的说明请参阅本节。

5.1 ViSearch

在搜索请求成功之后，结果列表以 ViResponseData 的形式传递给回调函数。您可以使用以下结果属性来实现自己的目的。

名称	类型	描述
hasError	布尔型	如果 Visenze 服务器返回错误，则为 true。
error	字符串数组	如果有错误，返回服务器错误信息。
result	ViImageResult 数组	从服务器返回的图像结果列表。
reqId	字符串？	用于跟踪的请求 ID。更多详情请参阅第 7 节。
im_id	字符串？	结果中返回的图像 ID，表示刚刚上传的图像。它可以被重复使用以对同一图像进行上传搜索。更多详情请参阅图像搜索。

以下为 ViImageResult 的属性。

名称	类型	描述
im_name	字符串	图像的识别名称。
im_url	字符串？	如果可用，则给出图像的 url。例如，当 getAllFl 设置为 true 或在 fl 属性中包含 im_url 时。
score	浮点？	介于 0.0 到 1.0 之间的浮点值。请参阅第 6.3 节“结果分数”。
metadataDict	字典	从服务器返回的其他元数据。请参阅第 6.1 节“检索元数据”。

 // example
 ViSearch.sharedInstance.uploadSearch( params: params!,
                             successHandler: {
                                (data : ViResponseData?) -> Void in
                                // Do something when request succeeds
                                // preview by calling : dump(data)
                                // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server

                                if let data = data {
                                    // check if that there is no error
                                    if !data.hasError {
                                        for imgResult in data.result {
                                            // process img result
                                        }
                                    }
                                }

            },
                             failureHandler: {
                                (err) -> Void in
                                // Do something when request fails e.g. due to network error
                                print ("error: \(err.localizedDescription)")
        })

您可以通过在 ViBaseSearchParams 中配置基本搜索参数来提供分页参数，以通过图像搜索结果的分页进行控制。由于结果以图像页面的列表形式返回，因此使用 limit 来设置每页的结果数量，使用 page 来指明页数。

名称	类型	描述
page	整数	可选参数，用于指定结果页码。结果的第一页为 1。默认值为 1。
limit	整数	可选参数，用于指定每页结果的数量。默认值为 10。

// For example, when the server side has 60 items, the search operation will return
// the first 30 items with page = 1 and limit = 30. By changing the page to 2,
// the search will return the last 30 items.
...        
params.page = 2;
params.limit = 30;

// start searching
...

5.2 产品搜索

搜索请求成功后，结果以 ViProductSearchResponse 形式传递给回调函数。您可以使用以下属性来满足您的需求。

名称	类型	描述
requestId	字符串	与 ViSearch 相同
状态	字符串	请求状态，可以是“OK”、“警告”或“失败”
imageId	字符串	图片ID。可以用于再次搜索而不需要重新上传
page	Int	结果页码
limit	Int	每页结果数量
total	Int	搜索结果总数。
error	ViErrorMsg	如果请求失败，将返回错误信息和代码，即当状态为“警告”或“失败”时
productTypes	[ViProductType]	检测到的产品类型及其在(x1,y1,x2,y2)格式下的边界框
result	[ViProduct]	搜索结果中的产品列表。第一版中的重要字段。如果不存在，则设置为空白。请注意，我们将在“data”字段中显示客户的原始目录字段
catalogFieldsMapping	[String:String]	原始目录的字段映射
facets	[ViFacet]	筛选的断言字段值和响应列表
productInfo	[String:Any]	仅适用于VSR，返回查询产品信息
objects	[ViProductObjectResult]
groupResults	[ViGroupResult]	仅在设置group_by时适用
groupByKey	字符串	仅在设置group_by时适用
querySysMeta	[String:String]	查询图像/产品的系统元数据

6. 高级搜索参数

6.1 检索元数据

要检索搜索结果中的元数据，请在基本搜索属性中提供元数据键列表作为fl（字段列表）

params!.fl = ["price","brand","im_url"]

要检索图像结果的所有元数据，请指定get_all_fl参数并将其设置为true

params.getAllFl = true;

在结果回调中，您可以读取元数据

successHandler: {
                    (data : ViResponseData?) -> Void in
                    // Do something when request succeeds
                    // preview by calling : dump(data)
                    // check ViResponseData.hasError and ViResponseData.error for any errors return by ViSenze server

                    if let data = data {
                        // check if that there is no error
                        if !data.hasError {
                            for imgResult in data.result {
                                // process img result
                                // example: extract price meta-data if available in server
                                print imgResult.metadataDict["price"]
                            }
                        }
                    }

}

只能从ViSearch检索到类型为string、int和float的元数据。没有可用于检索的文本类型元数据。

6.2 筛选结果

要根据元数据值筛选搜索结果，提供元数据键到筛选值的映射作为fq（过滤查询）属性

...

// the type of "count" on db schema is int,
// so we can specify the value range, or do a value match

params?.fq["count"] = "0, 199"
params?.fq["count"] = "199"

// the type of "price" on db schema is float,
// so we can specify the value range, or do a value match
params?.fq["price"] = "0.0, 199.0"
params?.fq["price"] = "15.0"

// the type of "description" on db schema is string, so we can do a string match.
params?.fq["description"] = "wooden"

// start searching
...

以下表格列出了每种元数据类型的查询语法

类型	FQ
string	元数据值必须与查询值完全匹配，例如，“Vintage Wingtips”不会匹配“vintage wingtips”或“vintage”
text	元数据值将使用全文搜索引擎进行索引，并支持模糊文本匹配，例如，“一双高质量的皮革翼尖”会匹配该短语中的任何单词
int	元数据值可以是与查询值完全匹配与范围查询`minValue,maxValue`匹配，例如，int值`1, 99`和`199`会匹配范围查询`0,199`，但不会匹配范围查询`200,300`
float	元数据值可以是与查询值完全匹配与范围查询`minValue,maxValue`匹配，例如，float值1.0，99.99和199.99会匹配范围查询`0.0,199.99`，但不会匹配范围查询`200.0,300.0`

6.3 结果评分

ViSearch图像搜索结果按降序排列，即从最高分数到最低分数，分数范围从1.0到0.0。默认情况下，不返回每个结果的分数。您可以启用分数参数以检索每个图像结果的分数

...

params.score = true; // result will include score for every image

// start searching
...

如果您需要将搜索结果限制在最低分数到最高分数之间，请指定score_min和/或score_max参数

...

params.score = true; // result will include score for every image
params.scoreMin = 0.3; // the minimum score is 0.3  
params.scoreMax = 0.8; // the maximum score is 0.8

// start searching. Every image result will have a score within [0.3, 0.8].
...

6.4 自动物体识别Beta

使用自动物体识别，ViSearch /uploadsearch API可以智能地检测查询图像中存在的物体，并建议最佳匹配产品类型以运行搜索。

您可以通过设置API参数“detection=all”来在上传搜索中启用此功能。我们现在能够检测各种时尚商品，包括上衣、裙子、下装、鞋子、包包、手表和印度民族服装。随着我们对其他类别的探索，这个列表会不断扩展。

注意：此功能目前仅适用于时尚应用程序类型。您需要确保您的应用类型在ViSenze控制台上配置为“时尚”。

params.detection = "all";

您可以使用Box参数限制图像区域[x1, y1, x2, y2]，作为您要搜索的图像部分。当您输入宽度为0和高度为0的框，例如：“box”:[574,224,574,224]。我们将将其视为一个点，并在当前位置检测对象。

您也可以通过将检测参数配置为特定的产品类型（例如“detection={type}”）来识别上传查询图像中的特定类型的对象。我们的API将在该产品类型内运行搜索。

检测上传图像中包包的示例请求

params.detection = "bag";

检测到的产品类型、匹配得分和检测到的对象的框区域将列在product_types中。从查询图像中可以检测到多个对象，并按得分从高到低排序。我们的API支持的完整产品类型列表也会返回在product_types_list中。

6.5 筛选功能

您可以通过发送要启用筛选的字段列表来获取筛选结果。

Facet字段需要在ViSenze控制台上标记为可搜索的。即使文本字段被标记为可搜索的，也不支持作为筛选字段。系统将返回数值字段的值范围、最小值和最大值，数值字段类型为“int”，“float”。
只有存在于当前搜索结果中的筛选值才会返回。例如，如果您的搜索结果包含10个独特的品牌，则筛选器将返回这10个品牌的值。
筛选值列表按项目计数降序排列。当值设为所有（facets = *）时，所有可搜索字段都会用作筛选字段。

名称	类型	描述
facets	array	启用筛选功能的字段列表。
facets_limit	Int	返回的筛选值得数限制。仅针对非数值字段。
facets_show_count	布尔值	选择是否在响应中显示筛选器计数。

params?.facets = ["price", "brand"]
params?.facetsLimit = 10
params?.facetShowCount = true

// view facet results
ViResponseData.facets

// numerical facet would have a min and max
// ViFacet.min , ViFacet.max

// string fields would have a count (if facetShowCount is set )
// ViFacet.items

7. 事件跟踪

为了提高搜索性能并获取有用的数据洞察，建议向我们的视觉搜索结果发送用户交互（行动）。

7.1 设置跟踪

根据您是否使用新的ViSenze控制台（console.visenze.com）或ViSenze仪表板（dashboard.visenze.com），您可以如下初始化ViSenze跟踪器。

import ViSearch

...

# for ViSenze Console
let tracker = ViProductSearch.sharedInstance.newTracker()

# for sending events in China
let cnTracker = ViProductSearch.sharedInstance.newTracker(forCn: true)

# for ViSenze old dashboard
let tracker = ViSearch.sharedInstance.newTracker(code: "your-code")

为了获取用于分析的ViSenze自动生成的uid和会话ID，您可以调用

// get uid
ViProductSearch.sharedInstance.getUid()

// get session ID
ViProductSearch.sharedInstance.getSid()

7.1.1 多个投放设置

如果需要创建多个跟踪器实例，可以多次实例化ViSenzeTracker。

var placement111 = ViProductSearch()
placement111.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID)
var tracker111 = placement111.newTracker()

var placement222 = ViProductSearch()
placement222.setUp(appKey: "YOUR_KEY", placementId: YOUR_PLACEMENT_ID)
var tracker222 = placement222.newTracker()

7.2 发送事件

目前我们支持以下事件动作：click（点击）、view（查看）、product_click（产品点击）、product_view（产品查看）、add_to_cart（添加到购物车）、add_to_wishlist（添加到心愿单）和transaction（交易）。action参数可以是任意字符串，并可以发送自定义事件。

注意，发送交易ID、产品图片URL和产品位置是可选的。如果没有其他字段，可以使用相应的方法，如VaEvent.newProductClickEvent (queryId: "", pid: "")来创建事件。

要发送事件，首先从搜索结果回调中检索搜索查询ID

successHandler: {
                    (data : ViResponseData?) -> Void in
                       if let data = data {
                           let queryId = data.reqId
                       }

}

然后可以按如下方式发送相关事件

# send product click
let productClickEvent = VaEvent.newProductClickEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(productClickEvent) { (eventResponse, networkError) in
   
}

# send product impression
let impressionEvent = VaEvent.newProductImpressionEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(impressionEvent)

# send Transaction event e.g order purchase of $300
let transEvent = VaEvent.newTransactionEvent(queryId: "xxx", transactionId:"your trans id", value: 300)
tracker.sendEvent(transEvent)

# send Add to Cart Event
let add2Cart = VaEvent.newAdd2CartEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(add2Cart)

# send result load event
let resLoadEvent = VaEvent.newResultLoadEvent(queryId: "xxx", pid:"your query product id")
tracker.sendEvent(resLoadEvent)

用户操作（多个）也可以通过批量事件处理器发送。

此批量事件方法的典型用例是通过批量发送来聚合所有交易。此SDK将自动生成交易ID以将交易作为订单分组。

tracker.sendEvents(eventList)

以下是各种参数的简要说明

字段	描述	必需
queryId	搜索请求的请求ID。此reqid可以从搜索响应处理器获取：`ViResponseData.reqId`	是
action	事件动作。目前我们支持以下事件动作：`click`、`view`、`product_click`、`product_view`、`add_to_cart`和`transaction`。	是
pid	产品ID（通常这是`im_name`），对应此产品。可以采用`ViImageResult.im_name`来检索。	为产品查看、产品点击和添加到购物车事件所必需。
imgUrl	产品图片URL（通常这是`im_url`），对应此产品。可以采用`ViImageResult.im_url` 来检索。	为产品查看、产品点击和添加到购物车事件所必需。
pos	产品在搜索结果中的位置，例如点击位置/查看位置。请注意，这从1开始，而不是0。	为产品查看、产品点击和添加到购物车事件所必需。
transactionId	交易ID	为交易事件所必需。
value	交易金额，例如订单金额。	为交易事件所必需。
uid	唯一的用户/设备ID。如果没有提供，将生成一个随机的（非可定制的）UUID来跟踪浏览器。	No
tag	用于将相关用户流程中的事件分类或分组的一般字符串。例如：`privacy_flow`、`videos`、`search_results`。通常，类别用于分组相关的UI元素。最大长度：32。	No
名称	事件名称，例如`open_app`、`click_on_camera_btn`。最大长度：32。	No
标签	主交互对象（如产品标题、页面标题）的标签。与`action`一起，可以用来确定事件是否唯一，例如，如果用户单击同一产品两次，则只记录一个唯一单击。最大长度：32。	No
fromReqId	通用请求ID字段，用于指定导致此事件哪个请求。例如，导致购物的点击请求ID。链可以是这个查询ID → 点击ID → 购买。最大长度：32。	No
source	通过标记来划分流量，例如从相机，从桌面。最大长度：32。	No
品牌	产品品牌。最大长度：64。	No
价格	产品价格。数值字段，如果提供，必须是>=0的有效数字。	No
货币	ISO 3字符代码，例如“USD”。如果提供，将验证。	No
productUrl	产品URL。最大长度：512。	No
广告活动	广告活动的长度最大：64。	No
adGroup	广告组名称（仅适用于广告活动）	No
创意	创意名称（仅适用于广告活动）	No
n1	自定义数字参数。	No
n2	自定义数字参数。	No
n3	自定义数字参数。	No
n4	自定义数字参数。	No
n5	自定义数字参数。	No
s1	自定义字符串参数。最大长度：64。	No
s2	自定义字符串参数。最大长度：64。	No
s3	自定义字符串参数。最大长度：64。	No
s4	自定义字符串参数。最大长度：64。	No
s5	自定义字符串参数。最大长度：64。	No
json	自定义json参数。最大长度：512。	No

8. 开发者说明

SDK需要ViSenze Tracking库作为依赖项https://github.com/visenze/visenze-tracking-swift。对于本地开发，可以在ViSearchSDK文件夹内运行以下命令来拉取依赖项。

# first update version within Cartfile

# pull latest changes and build framework
carthage update --use-xcframeworks

ViSearchSDK 1.11.0

ViSearchSDK 1.11.0

ViSearchSDK 1.11.0

ViSearch Swift SDK 和 Demo 源代码

目录

1. 概述

2. 设置

2.1 设置Xcode项目

2.2 导入 ViSearch Swift SDK

2.2.1 使用 CocoaPods

2.2.2 使用 Carthage

2.2.3 使用手动方法

2.3 添加隐私用途描述

3. 初始化

3.1 ViSearch

3.2 产品搜索

3.2.1 多放置的设置

4. 解决方案API

4.1 ViSearch

4.1.1 形似推荐

4.1.2 通过图像搜索

4.1.2.1 选择框

4.1.2.2 缩放设置

4.1.3 通过颜色搜索

4.1.4 多产品搜索

4.2 ProductSearch

4.2.1 图片搜索

4.2.2 推荐

5. 搜索结果

5.1 ViSearch

5.2 产品搜索

6. 高级搜索参数

6.1 检索元数据

6.2 筛选结果

6.3 结果评分

6.4 自动物体识别Beta

6.5 筛选功能

7. 事件跟踪

7.1 设置跟踪

7.1.1 多个投放设置

7.2 发送事件

8. 开发者说明