Virtusize iOS 集成

日语

Virtusize 通过让客户将他们想买的商品的尺寸与他们已拥有的参考商品的尺寸进行比较（在零售商的商品页面上），帮助零售商在线展示服装、鞋类和包的尺寸和适合度。这是通过比较零售商产品的轮廓与客户参考商品的轮廓来实现的。Virtusize 是一个小工具，当点击位于商品页面上尺寸选择旁边的 Virtusize 按钮时打开。

在 https://www.virtusize.com 上了解更多关于 Virtusize 的信息

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

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

需求

苹果iOS 12.0+
Xcode 12+
Swift 5.0+

安装

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

CocoaPods

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

$ gem install cocoapods

要将Virtusize SDK集成到您的Xcode项目中，请使用CocoaPods指定它，在您的Podfile中添加以下配置

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

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

然后，运行以下命令

$ pod repo update
$ pod install

Swift 包管理器

从2.3.2版本开始，Virtusize支持通过Swift 包管理器进行安装。

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

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对象
- 一个用于在Virtusize服务器中引用产品的externalId
- 产品图片的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中，单击您的项目标签的Info选项卡，并选择URL Types。

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

(2) 设置应用的bundle ID

在App Delegate的application(_:didFinishLaunchingWithOptions:)方法中，使用应用的bundle 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
}

❗IMPORTANT

URL类型必须包含您的应用bundle ID并以.virtusize结尾。
如果您有多个应用目标，为它们添加URL类型。

4. 实现 VirtusizeMessageHandler (可选)

VirtusizeMessageHandler 协议有两个必需的方法

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

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. 监听产品数据检查（可选）

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

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

Virtusize.productDataCheckDidFail，它接收包含错误原因消息的 UserInfo。
Virtusize.productDataCheckDidSucceed，如果调用成功则将被发送。

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

您可以检查示例项目以查看可能的实现方法之一。

Virtusize 视图

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

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

1. Virtusize 按钮

(1) 简介

VirtusizeButton是我们SDK中最简单的UI按钮。它会在网页视图中打开我们的应用，以支持客户找到合适的尺寸。

(2) 默认样式

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

青色主题	黑色主题

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

(3) 使用方法

A. 添加Virtusize按钮

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

B. 通过使用Virtusize.setVirtusizeView方法，将Virtusize按钮以及您传递给Virtusize.load的VirtusizeProduct对象连接到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.setVirtusizeView 方法将 Virtusize InPage Standard 与 VirtusizeProduct 对象（您已传递给 Virtusize.load）连接起来。
```
Virtusize.setVirtusizeView(self, inPageStandard, product: product)
```

B. 设计指南

默认设计

有两大种默认设计。

青色主题黑色主题
布局变化

以下是一些可能的布局

1 缩略图 + 2 行信息 2 缩略图 + 2 行信息

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

(3) InPage简版

这是InPage的简短版本，可以放置到您的应用中。简洁的设计适合那些客户正在浏览产品图片和尺寸表的情况。

A. 使用方式

添加一个VirtusizeInPageMini
- 您可以使用以下方式在您的店铺的产品页面上使用Virtusize InPage Mini：
  - 在Xcode的Interface Builder中创建一个UIView，在Identity检查器中将自定义类设置为VirtusizeInPageMini，并确保在加载时隐藏该视图。
    
    请务必为InPage Mini设置约束，然后转到Size检查器 -> 找到固有尺寸 -> 选择占位符，以便动态高度依赖于其内容。
  - 或者程序化地添加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
  - 12点（消息）
  - 10点（按钮）
- 韩语
  - Noto Sans CJK KR
  - 12点（消息）
  - 10点（按钮）
- 英语
  - San Francisco（系统默认）
  - 14点（消息）
  - 12点（按钮）
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	"Small", "Large" 等。	如果尺寸名称与产品页面不相同，增加尺寸别名
variantId	String	"A001_SIZES_RED"	在商品 SKU、颜色或尺寸有多个选项时设置在产品上的 ID
imageUrl*	String	"http://images.example.com/coat.jpg"	商品图片的 URL
color	String	"RED", "R" 等。	商品的色彩
gender	String	"W", "Women" 等。	表示性别的标识符
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. 发送订单

当用户下单时，在您的活动或碎片中调用 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)")
})

在原生化阅器应用中启用virtusize的sns登录

使用Virtusize Auth SDK。

构建

您需要安装SwiftLint。

make build

运行所有测试

make test

路线图

请查看路线图以获取即将推出的功能和预期发布日期。

1 缩略图 + 2 行信息	2 缩略图 + 2 行信息

1 缩略图 + 1 行信息	2 动画缩略图 + 2 行信息

VirtusizeCore 2.5.9

VirtusizeCore 2.5.9

VirtusizeCore 2.5.9

Virtusize iOS 集成

目录

需求

安装

CocoaPods

Swift 包管理器

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. 设计指南

默认设计

布局变化

推荐位置

UI定制

(3) InPage简版

A. 使用方式

B. 设计指南

默认设计

推荐位置

默认字体

UI自定义

订单API

1. 初始化

2. 创建用于订单数据的 VirtusizeOrder 结构

3. 发送订单

在原生化阅器应用中启用virtusize的sns登录

构建

运行所有测试

路线图

许可