ProductCat 1.0.0

ProductCat 1.0.0

×

由 Ngo Hung 维护。

ProductCat 1.0.0

  • 由
  • Ngo Hung

ProductCat Swift SDK 和演示源代码

Swift

目录

  1. 概览
  2. 设置
  3. 初始化
  4. 解决方案 API
  5. 搜索结果
  6. 数据隐私流程

1. 概览

我们的 ProductCat (产品目录) API 允许您通过自动编目产品以更容易地查找和搜索产品。ProductCat API 文档。

此 SDK 是一个开源软件，以便轻松地将 ProductCat 搜索 API 集成到您的 iOS 应用程序中。它提供了三种搜索方法 - 通过图像搜索产品、通过文本关键词搜索产品和获取搜索结果页面。

ProductCat 数据库基于全球的 country 及其地理区域进行分割。您必须在调用产品搜索 API 时带有 country 参数，以确保只返回可运往该国家的产品。

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

支持的 iOS 版本：iOS 10.x 及更高版本

2. 设置

2.1 运行示例

示例应用的源代码与 SDK 一起提供 (示例)。您只需在 Xcode 中打开 ProductCatExample.xcworkspace 并运行示例。

screenshot

您需要在AppDelegate文件中通过使用您的应用程序密钥初始化ProductCat客户端。

// TODO: fill in your app key and search country here
ProductCat.sharedInstance.setup(appKey: "YOUR_APP_KEY", country: ExampleSettings.getCountry() ?? "SG")

2.2 设置Xcode项目

2.3 导入ProductCat Swift SDK

2.3.1 使用CocoaPods

首先需要安装CocoaPods的Ruby包

sudo gem install cocoapods --pre

然后转到您的项目目录中创建一个空的Podfile

cd /path/to/Demo
pod init

按照以下方式编辑Podfile

platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'ProductCat'
end
...

安装SDK

pod install

应创建Demo.xcworkspace项目。

2.3.2 手动方式

您还可以直接下载iOS SDK。要使用它，解压缩并將 ProductCat 项 目拖動到您的項目中。

  • 打开《ProductCat》文件夹，并将《ProductCat》拖入您应用程序Xcode项目的项目导航器中。

    它应该出现在您的应用程序蓝色项目图标下方的嵌套位置。它是在所有其他Xcode组之上还是之下并不重要。

  • 在项目导航器中选择《ProductCat.xcodeproj》，并验证部署目标与您的应用程序目标匹配。

  • 接下来，在项目导航器中选择您的应用程序项目，导航到目标配置窗口，然后在侧边栏中的“targets”标题下选择应用程序目标。

  • 在该窗口顶部的标签栏中，打开“Build Phases”面板。

  • 在“Link Binary with Libraries”部分下方点击+按钮。

  • 选择《ProductCat.framework》。

  • 您还需要点击+按钮来添加‘New Copy Files Phase’，并将‘Frameworks’设置为目的地，并将ProductCat.framework复制到您的项目中。

此时，《ProductCat.framework》被注册为目标依赖项、链接框架和嵌入框架。

完成！

2.4 添加隐私使用描述

iOS 10+需要用户权限才能访问相机和相册。如果您的应用程序需要这些访问，请在Info.plist中添加NSCameraUsageDescription和NSPhotoLibraryUsageDescription的描述。详细信息请参阅这里。

3. 初始化

ProductCat客户端在使用前必须用app_key初始化。

import ProductCat

...
// using default client which will connect to Visenze's server
// the country is passed to select the corresponding search points
// We provided 2 different points for China and the rest of the world
// productcat.visenze.com and productcat.visenze.com.cn
ProductCat.sharedInstance.setup(appKey: "YOUR_APP_KEY", country: "SG")
        
// specify custom timeout
ProductCat.sharedInstance.setup(baseUrl: "https://productcat.visenze.com", appKey: "YOUR_APP_KEY", country: "SG", timeout:20 )

...

4. 解决方案API

4.1 通过图片搜索

POST /summary/products

通过图像搜索解决方案是在给定查询图像的情况下，在全球产品数据库中搜索视觉上相似的产品。您应构建 UIImage 对象并将它传递给 ImageSearchParams 以开始搜索。请还指定 country 参数以定义您想搜索哪个本地数据库。

  • 使用图像
import ProductCat
...

let image = UIImage(named: "someImage.png")
let params = ImageSearchParams(country: "SG", image: image!)

ProductCat.sharedInstance.imageSearch(params: params,
                    successHandler: {
                        (data : ProductSummaryResponse?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check data.hasError and data.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 传递给 ImageSearchParams 来开始搜索。
import ProductCat
...

let params = ImageSearchParams(country: "SG", imUrl: "http://somesite.com/sample_image.png")
        
...
  • 如果您正在对先前上传的图像进行细化，例如调整框的大小，您可以传递搜索结果中返回的 im_id 来开始搜索，而不是再次上传图像。
import ProductCat
...

let params = ImageSearchParams(country: "SG", imId: "visenze_image_id_returned in previous search")
        
...

4.1.1 选择框

如果您要搜索的对象只占据您图像的一小部分，或者同一图像中存在其他无关对象，那么搜索结果可能会不准确。请使用“框”参数来细化图像的搜索区域以提高准确性。盒坐标是以上传图像的原始大小为基准设置的。注意：坐标系使用像素作为单位，而不是点。

// create the box to refine the area on the searching image
// Box(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 = ImageSearchParams(.....)

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

4.1.2 调整大小设置

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

为了减少上传搜索延迟，默认情况下，该方法会复制您的图像文件，并且在原始的任意一个大小超过 512 像素的情况下将复制的副本调整为 512x512 像素。这是降低搜索延迟的同时仍然适用于一般使用情况的优化大小。

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

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

如果您的图像包含精细的细节，例如纺织图案和纹理，您可以使用更大的图像进行搜索以获得更好的搜索结果。

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

// 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?.imgSettings = ImageSettings(setting: .highQualitySetting)

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

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

4.2 搜索结果 API

POST /summary/products/srp

搜索结果页面 API 用于获取一个网址，在浏览器中显示搜索结果。所有在 /summary/products 中使用的参数也都适用于此 API。

import ProductCat
...

ProductCat.sharedInstance.imageSearchResultPage(params: params,
                    successHandler: {
                        (data : ProductSummaryResponse?) -> Void in
                        // Do something when request succeeds
                        // preview by calling : dump(data)
                        // check data.hasError and data.error for any errors return by ViSenze server
                        // open the search results in a browser
                        
                        if let searchResultsUrl = data.srpUrl, let url = URL(string: searchResultsUrl) {
                        let vc = SFSafariViewController(url: url, entersReaderIfAvailable: false)
               vc.delegate = self
               self.present(vc, animated: true)
                        
                        }
                        
                        
                    },
                    failureHandler: {
                        (err) -> Void in
                        // Do something when request fails e.g. due to network error
                        print ("error: \\(err.localizedDescription)")
					})

...

4.3 文本搜索

GET /summary/products

文本搜索解决方案是通过给定的文本关键词来搜索类似产品。

import ProductCat
...

let textSearchParams = TextSearchParams(country: "SG", q: "some keywords")
ProductCat.sharedInstance.textSearch(params: textSearchParams,
                             successHandler: {
             (data : ProductSummaryResponse?) -> Void in
                 // Do something when request succeeds
                 // preview by calling : dump(data)
                 // check data.hasError and data.error for any errors return by ViSenze server
                 dump(data)
                 
              
                               
         },
        failureHandler: {
             (err) -> Void in
             // Do something when request fails e.g. due to network error
             print ("error: \\(err.localizedDescription)")
            
         })

5. 搜索结果

搜索请求成功后，搜索结果将以

ProductSummaryResponse
的形式传递给回调函数。您可以使用以下结果属性来满足自己的需求。

名称 类型 描述
hasError 布尔值 true 如果 Visenze 服务器返回错误。
error 字符串数组 如果有的话，返回服务器发送的错误信息。
result ProductSummary 数组 服务器返回的产品列表。
reqid 字符串 用于调试的请求ID。
imId 字符串 结果中返回的图像ID，代表刚刚上传的图像。它可以被重新使用来进行同一图像的另一次搜索。

以下为表示产品的 ProductSummary 属性。

名称 类型 描述
pid 字符串 产品ID。
mainImage 字符串 图像URL
标题 字符串 产品标题
minPrice 字符串 产品价格
priceUnit 字符串 3个字母的ISO货币代码，例如 "USD"。
productUrl 字符串 产品URL
stores Store 数组 此产品销售所在店铺的列表。数组至少包含一个店铺。

6. 数据隐私流程

为了分析搜索性能和使用统计（如点击通过率、活跃用户、转化跟踪、留存率等），ProductCat SDK 使用 UIDevice.current.identifierForVendor?.uuidString 与 IDFA（来自 AdSupport.framework）来唯一标识用户。根据用户的统计信息，Visenze 将根据用户的偏好推送定制搜索结果和广告产品。

请注意，最终用户需要

  • 接受 Visenze 的隐私政策和使用条款才能使用我们的服务
  • （可选）接受广告条款以接收特别优惠、促销信息和产品推荐

ProductCat SDK 首次使用时会向用户展示“条款和条件”对话框。用户在使用 API 之前必须接受条款和条件。如果用户不接受条款，SDK 将在其回调中抛出错误，开发者可以选择是否再次显示同意表单或退出服务。


// error will be shown via failureHandler callback (ProductCatError.TERMS_NOT_ACCEPTED)

ProductCat.sharedInstance.imageSearch(params: params,
                    successHandler: {
                        
                    },
                    failureHandler: {
                        (err) -> Void in
                        
                        if (err == ProductCatError. ProductCatError.TERMS_NOT_ACCEPTED) {
                        
                        // show terms again
                        ProductCat.sharedInstance.showConsentForm(nil)
                        
                        }
					})

您可以使用以下方法显示同意表单并检查用户是否已接受 ViSenze 条款

// show the form
ProductCat.sharedInstance.showConsentForm()

// check if user accept or reject the terms
ProductCat.sharedInstance.isAcceptedVisenzeTerms()