Virtusize iOS 集成

日本語

Virtusize 有助于零售商在线展示服装、鞋子和包的尺码和尺码，通过让客户将他们想要购买的物品（在零售商的产品页面上）的尺寸与他们已经拥有的物品（参考物品）的尺寸进行比较来做到这一点。这是通过将零售商产品的轮廓与客户参考物品的轮廓进行比较来完成的。Virtusize 是一个在小部件中打开时点击 Virtusize 按钮，该按钮位于产品页面上尺寸选择旁边的工具。

了解 Virtusize 的更多信息，请访问 https://www.virtusize.com

您需要一个唯一的 API 密钥和一个管理员账户，仅限于 Virtusize 客户。要成为客户，请联系我们的销售团队。

这只是用于原生 iOS 设备的集成脚本。有关网络集成，请参阅 https://developers.virtusize.com 上的开发者文档。

需求

iOS 10.3+
Xcode 12+
Swift 5.0+

安装

如果您想继续使用较旧的1.x.x版本，请参阅分支 v1。

CocoaPods

使用CocoaPods依赖管理器进行安装。您可以使用以下命令安装：

$ gem install cocoapods

要使用CocoaPods将Virtusize SDK集成到Xcode项目中，请在您的Podfile中指定它

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.3'
use_frameworks!

target '<your-target-name>' do
pod 'Virtusize', '~> 2.5.1'
end

然后，运行以下命令：

$ pod repo update
$ pod install

Swift Package Manager

从2.3.1版本开始，Virtusize支持通过Swift Package Manager安装

在Xcode中，选择文件 > Swift包 > 添加包依赖...，并将"https://github.com/virtusize/integration_ios.git"作为仓库URL输入。
选择最小版本为2.5.1
点击

Carthage

使用Carthage依赖管理器进行安装。您可以使用以下命令安装：

brew install carthage

要使用Carthage将Virtusize SDK集成到Xcode项目中，请在您的Cartfile中指定它

github "virtusize/integration_ios"

然后，运行以下命令：

$ carthage update

根据 Carthage 文档指引进一步了解如何链接框架并构建它。

设置

1. 初始化

在 App 代理的 application(_:didFinishLaunchingWithOptions:) 方法中设置 SDK。

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Virtusize.APIKey is required
    Virtusize.APIKey = "15cc36e1d7dad62b8e11722ce1a245cb6c5e6692"
    // For using the Order API, Virtusize.userID is required
    Virtusize.userID = "123"
    // By default, the Virtusize environment will be set to .global
    Virtusize.environment = .staging
    Virtusize.params = VirtusizeParamsBuilder()
        // By default, the initial language will be set based on the Virtusize environment
        .setLanguage(.JAPANESE)
        // By default, ShowSGI is false
        .setShowSGI(true)
        // By default, Virtusize allows all the possible languages including English, Japanese and Korean
        .setAllowedLanguages([VirtusizeLanguage.ENGLISH, VirtusizeLanguage.JAPANESE])
        // By default, Virtusize displays all the possible info categories in the Product Details tab,
        // including "modelInfo", "generalFit", "brandSizing" and "material".
        .setDetailsPanelCards([VirtusizeInfoCategory.BRANDSIZING, VirtusizeInfoCategory.GENERALFIT])
        .build()

    return true
}

环境是从您运行集成的区域，可以是 .staging、.global、.japan 或 .korea

您可以使用 VirtusizeParamsBuilder 设置 Virtusize.params，以更改集成的配置。以下表格显示了可能的配置方法

VirtusizeParamsBuilder

方法	参数类型	示例	描述	需求
setLanguage	VirtusizeLanguage	setLanguage(.JAPANESE)	设置集成将加载的初始语言。可能的值是 `VirtusizeLanguage.ENGLISH`、`VirtusizeLanguage.JAPANESE` 和 `VirtusizeLanguage.KOREAN`	否。默认情况下，初始语言将根据 Virtusize 环境设置。
setShowSGI	布尔值	setShowSGI(true)	确定是否将获取 SGI 并使用 SGI 流为用户添加用户生成项目到他们的衣橱。	否。默认情况下，ShowSGI 设置为 false
setAllowedLanguages	一个 `VirtusizeLanguage` 列表	setAllowedLanguages([VirtusizeLanguage.ENGLISH, VirtusizeLanguage.JAPANESE])	用户可以通过使用语言选择器切换到的语言	否。默认情况下，集成允许显示所有可能的语言，包括英语、日语和韩语。
setDetailsPanelCards	一个 `VirtusizeInfoCategory` 列表	setDetailsPanelCards([VirtusizeInfoCategory.BRANDSIZING, VirtusizeInfoCategory.GENERALFIT])	将会在产品详情选项卡中显示的信息类别。可能的类别有：`VirtusizeInfoCategory.MODELINFO`、`VirtusizeInfoCategory.GENERALFIT`、`VirtusizeInfoCategory.BRANDSIZING` 和 `VirtusizeInfoCategory.MATERIAL`	否。默认情况下，集成在产品详情选项卡中显示所有可能的信息类别。

2. 使用 Virtusize SDK 加载产品

在您产品页面的视图控制器中，您需要使用 Virtusize.load 来填充 Virtusize 视图

使用以下内容创建一个 VirtusizeProduct 对象
- 一个 externalId，该 ID 将用于在 Virtusize 服务器中引用产品
- 产品图片的 imageURL
将 VirtusizeProduct 对象传递给 Virtusize.load 方法

override func viewDidLoad() {
    super.viewDidLoad()

    // Declare a `VirtusizeProduct` variable, which will be passed to the `Virtusize` views in order to bind the product info
    let product = VirtusizeProduct(
        // Set the product's external ID
        externalId: "vs_dress",
        // Set the product image URL
        imageURL: URL(string: "http://www.example.com/image.jpg")
    )

    // Load the product in order to populate the `Virtusize` views
    Virtusize.load(product: product)
}

3. 启用 SNS 身份验证

SNS 身份验证流程需要切换到 SFSafariViewController，该控制器将加载一个网页，用户可以使用 SNS 账户进行登录。必须定义一个自定义 URL 方案，以便将登录响应从 SFSafariViewController 返回到您的应用程序。

您必须注册一个 URL 类型并将其发送到 VirtusizeAuth.setAppBundleId 方法。

(1) 注册 URL 类型

在 Xcode 中，点击您的项目标签页的信息，并选择 URL 类型。

添加一个新 URL 类型，并将 URL 方案和标识设置为 com.your-company.your-app.virtusize

(2) 设置应用程序的包 ID

在应用程序代理的 application(_:didFinishLaunchingWithOptions:) 方法中，使用应用程序的包 ID 调用 VirtusizeAuth.setAppBundleId 方法。

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	// Virtusize initialization omitted for brevity

	// Set the app bundle ID
	VirtusizeAuth.setAppBundleId("com.your-company.your-app")

	return true
}

❗重要

URL 类型必须包含您的应用程序包 ID，并且以 virtusize 结尾。
如果您有多个应用程序目标，请为所有目标添加 URL 类型。

4. 实现 VirtusizeMessageHandler（可选）

VirtusizeMessageHandler 协议有两个必需的方法

当控制器报告网络或反序列化错误时，会调用 virtusizeController(_:didReceiveError:)。
在控制器和 Virtusize API 之间交换数据时，会调用 virtusizeController(_:didReceiveEvent:)。`VirtusizeEvent` 是一个具有必需的 name 和可选 data 属性的 `struct`。

extension ViewController: VirtusizeMessageHandler {
    func virtusizeController(_ controller: VirtusizeWebViewController?, didReceiveEvent event: VirtusizeEvent) {
        print(event)
        switch event.name {
		    case "user-opened-widget":
            return
		    case "user-opened-panel-compare":
            return
		    default:
            return
        }
    }

    func virtusizeController(_ controller: VirtusizeWebViewController?, didReceiveError error: VirtusizeError) {
        print(error)
    }
}

5. 允许 Cookie 共享（可选）

VirtusizeWebViewController 接受一个可选的 processPool:WKProcessPool 参数，允许 Cookie 共享。

// Optional: Set up WKProcessPool to allow cookie sharing.
Virtusize.processPool = WKProcessPool()

6. 监听产品数据检查（可选）

当按钮使用 外部 ID 初始化时，SDK 将调用我们的 API 检查产品是否已解析并添加到我们的数据库中。

为了调试该API调用，您可以订阅NotificationCenter并观察两个Notification.Name别名

Virtusize.productDataCheckDidFail。当发生失败时，它会接收包含失败原因的消息的UserInfo。
如果调用成功，将发送Virtusize.productDataCheckDidSucceed。

如果检查失败，按钮将被隐藏。

您可以查看示例项目，以了解一种可能的实现方式。

Virtusize 视图

设置完SDK后，添加一个VirtusizeView允许您的客户找到他们理想的大小。

Virtusize SDK为客户端提供了两个主要的UI组件供使用

1. Virtusize 按钮

(1) 简介

VirtusizeButton是我们SDK中最简单的UI按钮。通过它，我们的应用将在web视图中打开，帮助客户找到合适的大小。

(2) 默认样式

在Virtusize SDK中，Virtusize按钮有两种默认样式。

蓝绿色调主题	黑色调主题

如果您喜欢，也可以自定义按钮样式。

(3) 使用方法

A. 添加Virtusize按钮

要在您的店铺的产品页面使用Virtusize按钮，您可以选择以下方法之一
- 在 Xcode 的界面构建器 Storyboard 中创建一个 UIButton，在身份检查器中将自定义类设置为 VirtusizeButton，并确保按钮在加载时隐藏。
- 或者通过程序添加 VirtusizeButton
```
let virtusizeButton = VirtusizeButton()
view.addSubview(virtusizeButton)
```
- 为了使用我们的默认样式，请将 VirtusizeButton 的属性 style 设为 VirtusizeViewStyle.TEAL 或 VirtusizeViewStyle.BLACK
```
virtusizeButton.style = .TEAL
```
- 您也可以自定义按钮的样式属性。例如，titlelabel 的文本、高度、宽度等。

B. 使用 Virtusize.setVirtusizeView 方法将 VirtusizeButton 以及 VirtusizeProduct 对象（您已传递给 Virtusize.load）连接到 Virtusize API。

Virtusize.setVirtusizeView(self, virtusizeButton, product: product)

2. Virtusize InPage

(1) 简介

Virtusize InPage 是一个按钮，类似于我们服务的启动按钮。按钮还充当一个尺寸指南，帮助客户找到合适的尺寸。

InPage 类型

Virtusize SDK 中有两种 InPage 类型。

InPage 标准版	InPage 小型版

⚠️注意⚠️

InPage 不能与 Virtusize 按钮同时实现。请为您的在线商店选择 InPage 或 Virtusize 按钮。
InPage Mini 必须始终与 InPage Standard 结合使用。

(2) InPage Standard

A. 使用方法

添加 VirtusizeInPageStandard
- 要在您商店的产品页面上使用 Virtusize InPage Standard，您可以选择以下任一方式：
  - 在Xcode的Interface Builder中创建一个UIView，然后在身份检查器中将自定义类设置为VirtusizeInPageStandard，并确保加载时视图是隐藏的。
    
    确保为InPage Standard设置约束，然后转到大小检查器 -> 找到内在尺寸 -> 选择占位符，以便动态高度取决于其内容。
  - 或者以编程方式添加Virtusize InPage Standard
```
let inPageStandard = VirtusizeInPageStandard()
view.addSubview(inPageStandard)
```
- 为了使用我们的默认样式，将VirtusizeInPageStandard的属性style设置为VirtusizeViewStyle.TEAL或VirtusizeViewStyle.BLACK
- 如果您想更改CTA按钮的背景颜色，可以使用属性inPageStandardButtonBackgroundColor来设置颜色
```
// Set the InPage Standard style to VirtusizeStyle.BLACK
inPageStandard.style = .BLACK
// Set the background color of the CTA button to UIColor.blue
inPageStandard.inPageStandardButtonBackgroundColor = UIColor.blue
```
```
// Set the InPage Standard style to VirtusizeStyle.TEAL
inPageStandard.style = .TEAL
// Set the background color of the CTA button to a custom color using ColorLiteral
inPageStandard.inPageStandardButtonBackgroundColor = #colorLiteral(red: 0.09803921569, green: 0.09803921569, blue: 0.09803921569, alpha: 1)
```
- 当您以编程方式添加VirtusizeInPageStandard并且想设置应用屏幕边缘与VirtusizeInPageStandard之间的水平间距时，可以使用setHorizontalMargin
  
  如果您想为InPage Standard设置一个直接宽度，请使用自动布局约束。
```
// Set the horizontal margins to 16
inPageStandard.setHorizontalMargin(view: view, margin: 16)

// Or set the direct width for InPage Standard programtically
inPageStandard.translatesAutoresizingMaskIntoConstraints = false
inPageStandard.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
inPageStandard.widthAnchor.constraint(equalToConstant: 350).isActive = true
```
- 如果您想更改InPage Standard的字体大小，可以使用属性messageFontSize和buttonFontSize。
```
inPageStandard.buttonFontSize = 12
inPageStandard.messageFontSize = 12
```
将Virtusize InPage Standard，以及 VirtusizeProduct **对象（您已传递到 ** Virtusize.load**) **通过使用Virtusize.setVirtusizeView方法连接到Virtusize API。
```
Virtusize.setVirtusizeView(self, inPageStandard, product: product)
```

B. 设计指南

默认设计

有两种默认设计变体。

蓝绿色调主题黑色调主题
布局变化

以下是一些可能的布局

1个缩略图 + 2行消息 2个缩略图 + 2行消息

1个缩略图 + 1行消息 2个动画缩略图 + 2行消息
推荐位置
- 靠近尺寸表
- 在尺寸信息部分
用户界面定制
- 您可以
  - 更改 CTA 按钮的背景颜色，只要它通过 WebAIM 对比测试。
  - 调整 InPage 的宽度，使其适用于您的应用程序宽度。
- 您不能
  - 更改界面组件，如形状和间距。
  - 更改字体。
  - 更改 CTA 按钮形状。
  - 更改消息。
  - 更改或隐藏框阴影。
  - 隐藏包含 VIRTUSIZE 标志和隐私政策文本链接的页脚。

(3) InPage Mini

这是 InPage 的迷你版本，可以放置在您的应用程序中。其低调设计适合客户浏览产品图片和尺寸表时的布局。

A. 使用方法

添加 Virtusize InPage Mini
- 要使用 Virtusize InPage Mini 在您的商店的产品页面上，您可以
  - 在 Xcode 的 Interface Builder 中创建一个 UIView，在身份检查器中将自定义类设置为 VirtusizeInPageMini，并确保在加载时隐藏视图。
    
    确保为 InPage Mini 设置约束，然后转到大小检查器 -> 找到 内在大小 -> 选择 占位符，以便高度动态地依赖于其内容。
  - 或以编程方式添加 Virtusize InPage Mini
```
let inPageMini = VirtusizeInPageMini()
view.addSubview(inPageMini)
```
- 若要使用我们的默认样式，请将 VirtusizeInPageMini 的属性 style 设置为 VirtusizeViewStyle.TEAL 或 VirtusizeViewStyle.BLACK。
- 如果您想更改条形的背景颜色，可以使用属性 inPageMiniBackgroundColor 设置颜色。
```
inPageMini.style = .TEAL
inPageMini.inPageMiniBackgroundColor = #colorLiteral(red: 0.09803921569, green: 0.09803921569, blue: 0.09803921569, alpha: 1)
```
- 当您以编程方式添加 VirtusizeInPageMini 并想设置应用程序屏幕边缘与 VirtusizeInPageMini 之间的水平边距时，您可以使用 setHorizontalMargin。
  
  如果您想为 InPage Mini 设置直接宽度，请使用自动布局约束。
```
// Set the horizontal margins to 16
inPageMini.setHorizontalMargin(view: view, margin: 16)

// Or set the direct width for InPage Standard programtically
inPageMini.translatesAutoresizingMaskIntoConstraints = false
inPageMini.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
inPageMini.widthAnchor.constraint(equalToConstant: 350).isActive = true
```
- 如果您想更改 InPage Mini 的字体大小，您可以使用属性 messageFontSize 和 buttonFontSize。
```
inPageMini.messageFontSize = 12
inPageMini.buttonFontSize = 10
```
将 Virtusize InPage Mini 连接至对象 VirtusizeProduct（您已将其传递给 Virtusize.load），然后通过使用 Virtusize.setVirtusizeView 方法将其连接到 Virtusize API。
```
Virtusize.setVirtusizeView(self, inPageMini, product: product)
```

B. 设计指南

默认设计

有两种默认设计变体。

蓝绿色调主题黑色调主题
推荐位置

产品图片下方在尺寸表下方或附近
默认字体
- 日语
  - Noto Sans CJK JP
  - 12pt（消息）
  - 10pt（按钮）
- 韩语
  - Noto Sans CJK KR
  - 12pt（消息）
  - 10pt（按钮）
- 英语
  - San Francisco（系统默认）
  - 14pt（消息）
  - 12pt（按钮）
UI 自定义
- 您可以
  - 只要它通过 WebAIM 对比测试，您就可以更改条目的背景颜色。
- 您不能
  - 更改字体。
  - 更改 CTA 按钮形状。
  - 更改消息。

订单 API

订单API允许Virtusize向您的客户提供他们的购买历史中最近购买的物品，并使用这些物品与他们想购买的新物品进行比较。

1. 初始化

在将订单发送给Virtusize之前，请确保设置用户ID。您可以在以下位置设置用户ID：

在应用程序启动前，在App委托的 application(_:didFinishLaunchingWithOptions:) 方法中

或者在

应用启动后，在您的视图中控制器

Virtusize.userID = "123"

2. 为订单数据创建一个 VirtusizeOrder 结构

VirtusizeOrder 结构将传递给 Virtusize.sendOrder 方法，并具有以下属性

注意： * 表示该属性是必需的

VirtusizeOrder

属性	数据类型	示例	描述
externalOrderId*	String	"20200601586"	客户端提供的订单ID
items*	“VirtusizeOrderItem”结构体的数组	请参见下表	订单物品的数组

VirtusizeOrderItem

属性	数据类型	示例	描述
externalProductId*	String	"A001"	客户端提供的外部产品ID。对产品必须是唯一的。
size*	String	"S", "M"，等。	尺码的名称
sizeAlias	String	"小型"，"大型"，等。	如果尺码名称与产品页面不一致，则添加尺码别名
variantId	String	"A001_SIZES_RED"	如果项目有几种选项，则设置在产品SKU、颜色或尺寸上的ID
imageUrl*	String	"http://images.example.com/coat.jpg"	物品的图像URL
color	String	"RED"，"R"，等。	物品的颜色
gender	String	"W"，"女性"，等。	性别标识符
unitPrice*	Float	5100.00	浮点数，表示产品价格，最大为12位数字，2位小数（12,2）
currency*	String	"JPY"，"KRW"，"USD"，等。	货币代码
quantity*	Int	1	购买的物品数量。如果未传递，则默认为1
url	String	"http://example.com/products/A001"	产品页面的URL。请确保这是用户可以访问的URL

示例

var virtusizeOrder = VirtusizeOrder(externalOrderId: "2020060812345")
let item = VirtusizeOrderItem(
    externalProductId: "A00001",
    size: "L",
    sizeAlias: "Large",
    variantId: "A00001_SIZEL_RED",
    imageUrl: "http://images.example.com/products/A00001/red/image1xl.jpg",
    color: "Red",
    gender: "W",
    unitPrice: 5100.00,
    currency: "JPY",
    quantity: 1,
    url: "http://example.com/products/A00001"
)
virtusizeOrder.items = [item]

3. 发送订单

当用户下单时，请在您的activity或fragment中调用Virtusize.sendOrder方法。`onSuccess`和`onError`回调是可选的。

Virtusize.sendOrder(
    virtusizeOrder,
    // This success callback is optional and gets called when the app successfully sends the order
    onSuccess: {
        print("Successfully sent the order")
},
    // This error callback is optional and gets called when an error occurs
    // when the app is sending the order
    onError: { error in
        print("Failed to send the order, error: \(error.debugDescription)")
})

在原生Webview应用中启用Virtusize的SNS登录

使用Virtusize Auth SDK

编译

您需要安装SwiftLint。

make build

运行所有测试

make test

路线图

请查看路线图以查找即将到来的功能和预期发布日期。


依赖于
VirtusizeAuth	= 1.1.0
VirtusizeCore	<= 2.5.9

1个缩略图 + 2行消息	2个缩略图 + 2行消息

1个缩略图 + 1行消息	2个动画缩略图 + 2行消息

Virtusize 2.5.9

Virtusize 2.5.9

Virtusize 2.5.9

Virtusize iOS 集成

目录

需求

安装

CocoaPods

Swift Package Manager

Carthage

设置

1. 初始化

2. 使用 Virtusize SDK 加载产品

3. 启用 SNS 身份验证

4. 实现 VirtusizeMessageHandler（可选）

5. 允许 Cookie 共享（可选）

6. 监听产品数据检查（可选）

Virtusize 视图

1. Virtusize 按钮

(1) 简介

(2) 默认样式

(3) 使用方法

2. Virtusize InPage

(1) 简介

InPage 类型

(2) InPage Standard

A. 使用方法

B. 设计指南

默认设计

布局变化

推荐位置

用户界面定制

(3) InPage Mini

A. 使用方法

B. 设计指南

默认设计

推荐位置

默认字体

UI 自定义

订单 API

1. 初始化

2. 为订单数据创建一个 VirtusizeOrder 结构

3. 发送订单

在原生Webview应用中启用Virtusize的SNS登录

编译

运行所有测试

路线图

许可协议