virtusize_flutter_sdk

Description:

virtusize flutter sdk

Virtusize Flutter SDK #

A Flutter plugin that wraps Virtusize Native SDKs for Android & iOS.
Table of Contents #


Introduction


Requirements


Usage


Setup

Android
Flutter

Initialization
Load Virtusize with the Product Details
Implement VirtusizeMessageHandler (Optional)





Implement Virtusize Widgets

Virtusize Button
Virtusize InPage

InPage Standard
InPage Mini





The Order API

Initialization
Create a VirtusizeOrder object for order data
Send an Order



Example


License


Introduction #
Virtusize helps retailers to illustrate the size and fit of clothing, shoes and bags online, by letting customers compare the measurements of an item they want to buy (on a retailer's product page) with an item that they already own (a reference item). This is done by comparing the silhouettes of the retailer's product with the silhouette of the customer's reference Item. Virtusize is a widget which opens when clicking on the Virtusize button, which is located next to the size selection on the product page.
Read more about Virtusize at https://www.virtusize.com
You will need a unique API key and an Admin account, only available to Virtusize customers. Contact our sales team to become a customer.

This is the integration for Flutter apps only. For web integration, refer to the developer documentation on https://developers.virtusize.com

Requirements #


iOS 10.3+
Specify the iOS version at least 10.3 in ios/Podfile:
platform :ios, '10.3'
copied to clipboard


Android 5.0+ (API Level 21+)
Set the minSdkVersion to at least 21 in android/app/build.gradle:
android {
defaultConfig {
minSdkVersion 21
}
}
copied to clipboard


Usage #


Add virtusize_flutter_sdk as a dependency in your pubspec.yaml file.
dependencies:
virtusize_flutter_sdk: ^1.0.1
copied to clipboard


Run flutter pub get in your terminal, or click Pub get in IntelliJ or Android Studio.


Setup #
1. Android #


Starting from API 30, Android requires package visibility in your AndroidManifest.xml to open URLs in an app.
To be able to open URLs for the SDK, add the required <queries> element to the AndroidManifest.xml.
<queries>
<intent>
<action android:name="android.intent.action.VIEW" />
<data android:scheme="https" />
</intent>
</queries>
copied to clipboard


To be able to open the Virtusize webview in a Fragment for the SDK, inherit from FlutterFragmentActivity instead of FlutterActivity in the android/app/src/main/MainActivity.
- import io.flutter.embedding.android.FlutterActivity
+ import io.flutter.embedding.android.FlutterFragmentActivity

- class MainActivity: FlutterActivity() {
+ class MainActivity: FlutterFragmentActivity() {
}
copied to clipboard


2. Flutter #
(1) Initialization
Use the VirtusizeSDK.instance.setVirtusizeParams function to set up the Virtusize parameters before calling runApp.
import 'package:virtusize_flutter_sdk/virtusize_flutter_sdk.dart';

Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
VirtusizeSDK.instance.setVirtusizeParams(
// Only the API key is required
apiKey: '15cc36e1d7dad62b8e11722ce1a245cb6c5e6692',
// For using the Order API, a user ID is also required. (can be set later)
userId: '123',
// By default, the Virtusize environment will be set to VSEnvironment.global
env: VSEnvironment.staging,
// By default, the initial language will be set according to the Virtusize environment
language: VSLanguage.jp,
// By default, ShowSGI is false
showSGI: true,
// By default, Virtusize allows all possible languages
allowedLanguages: [VSLanguage.en, VSLanguage.jp],
// By default, Virtusize displays all possible info categories in the Product Details tab
detailsPanelCards: [VSInfoCategory.generalFit, VSInfoCategory.brandSizing]
);

runApp(MyApp());
}
copied to clipboard
Possible argument configuration is shown in the following table:



Argument
Type
Example
Description
Required




apiKey
String
"api_key"
A unique API key is provided to each Virtusize client.
Yes


userId
String
"123"
Passed from the client if the user is logged into the client's app.
Yes, if the Order API is used.


env
VSEnvironment
VSEnvironment.staging
The environment is the region you are running the integration from, either VSEnvironment.staging, VSEnvironment.global, VSEnvironment.japan or VSEnvironment.korea.
No. By default, the Virtusize environment will be set to VSEnvironment.global.


language
VSLanguage
VSLanguage.jp
Sets the initial language that the integration will load in. The possible values are VSLanguage.en, VSLanguage.jp and VSLanguage.kr
No. By default, the initial language will be set based on the Virtusize environment.


showSGI
bool
true
Determines whether the integration should use SGI flow for users to add user generated items to their wardrobe.
No. By default, showSGI is set to false.


allowedLanguages
List<VSLanguage>
[VSLanguage.en, VSLanguage.jp]
The languages which the user can switch to using the Language Selector
No. By default, the integration allows all possible languages to be displayed, including English, Japanese and Korean.


detailsPanelCards
List<VSInfoCategory>
[VSInfoCategory.generalFit, VSInfoCategory.brandSizing]
The info categories which will be display in the Product Details tab. Possible categories are: VSInfoCategory.modelInfo, VSInfoCategory.generalFit, VSInfoCategory.brandSizing and VSInfoCategory.material
No. By default, the integration displays all the possible info categories in the Product Details tab.



(2) Load Virtusize with the Product Details
In the initState of your product page widget, you will need to use VirtusizeSDK.instance.loadVirtusize to populate the Virtusize widgets:

Create a VirtusizeClientProduct object with:

An exernalId that will be used to reference the product in the Virtusize server
An imageURL for the product image


Pass the VirtusizeClientProduct object to the VirtusizeSDK.instance.loadVirtusize function

/// Declare a global `VirtusizeClientProduct` variable,
/// which will be passed to the `Virtusize` widgets in order to bind the product info
VirtusizeClientProduct _product;

@override
void initState() {
super.initState();

_product = VirtusizeClientProduct(
// Set the product's external ID
externalProductId: 'vs_dress',
// Set the product image URL
imageURL: 'https://www.image.com/goods/12345.jpg'
);

VirtusizeSDK.instance.loadVirtusize(_product);
}
copied to clipboard
If you want to update the product to a different one while the user is on the same screen, assign a different VirtusizeClientProduct object to _product and reload the product using VirtusizeSDK.instance.loadVirtusize inside of setState() to re-build the widgets
setState(() {
_product = VirtusizeClientProduct(
externalProductId: 'vs_pants',
imageURL: 'https://www.image.com/goods/12345.jpg'
);
VirtusizeSDK.instance.loadVirtusize(_product);
});
copied to clipboard
(3) Implement VirtusizeMessageHandler (Optional)
You can register a VirtusizeMessageListener to listen for events and the ProductDataCheck result from Virtusize.
All the arguments for the VirtusizeSDK.instance.setVirtusizeMessageListener function are optional.
@override
void initState() {
super.initState();

VirtusizeSDK.instance.setVirtusizeMessageListener(
VirtusizeMessageListener(
vsEvent: (eventName) {
print("Virtusize event: $eventName");
},
vsError: (error) {
print("Virtusize error: $error");
},
productDataCheckSuccess: (productDataCheck) {
print('ProductDataCheck success: $productDataCheck');
},
productDataCheckError: (error) {
print('ProductDataCheck error: $error');
}
)
);
}
copied to clipboard
Implement Virtusize Widgets #
After setting up the SDK, add a Virtusize widget to allow your customers to find their ideal size.
Virtusize's Flutter SDK provides two main UI widgets for clients to use:
1. Virtusize Button #
(1) Introduction
VirtusizeButton is the simplest UI Button for our SDK. It opens our application in a web view to support customers finding the right size.
(2) Default Styles
There are two default styles of the Virtusize Button in our Virtusize SDK.



Teal Theme
Black Theme









If you like, you can also customize the button style.
(3) Usage


VirtusizeButton.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.Black, Widget child})
Create a VirtusizeButton widget with default Virtusize style and with the same VirtusizeClientProduct object that you have passed to the VirtusizeSDK.instance.loadVirtusize function
// A `VirtusizeButton` widget with default `Black` style
VirtusizeButton.vsStyle(product: _product)

// A `VirtusizeButton` widget with `Teal` style and a custom `Text` widget
VirtusizeButton.vsStyle(
product: _product,
style: VirtusizeStyle.Teal,
child: Text("Custom Text")
)
copied to clipboard
create a VirtusizeButton widget with your custom button widget:


VirtusizeButton({required VirtusizeClientProduct product, required Widget child})
// A `VirtusizeButton` widget with a custom `ElevatedButton` widget
VirtusizeButton(
product: _product,
child: ElevatedButton(
child: Text('Custom Button'),
// Implement the `onPressed` callback with the `VirtusizePlugin.instance.openVirtusizeWebView` function if you have customized the button
onPressed: () => VirtusizeSDK.instance.openVirtusizeWebView(_product))
)
)
copied to clipboard


2. Virtusize InPage #
(1) Introduction
Virtusize InPage is a button that behaves like a start button for our service. The button also behaves as a fitting guide that supports people to find the right size.
InPage types
There are two types of InPage in our Virtusize SDK.



InPage Standard
InPage Mini









⚠️Caution⚠️

InPage cannot be implemented together with the Virtusize button. Please pick either InPage or Virtusize button for your online shop.
InPage Mini must always be used in combination with InPage Standard.

(2) InPage Standard
A. Usage


VirtusizeInPageStandard.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.Black, double horizontalMargin = 16})
Create a VirtusizeInPageStandard widget with the default Virtusize style and the ability to change the horizontal margin, using the same VirtusizeClientProduct object that you have passed to the VirtusizeSDK.instance.loadVirtusize function
// A `VirtusizeInPageStandard` widget with default `Black` style and a default horizontal margin of `16`
VirtusizeInPageStandard.vsStyle(product: _product)

// A `VirtusizeInPageStandard` widget with `Teal` style and a horizontal margin of `32`
VirtusizeInPageStandard.vsStyle(
product: _product,
style: VirtusizeStyle.Teal,
horizontalMargin: 32
)
copied to clipboard
create a VirtusizeInPageStandard widget with the ability to change the button background color and the horizontal margin:


VirtusizeInPageStandard({required VirtusizeClientProduct product, Color buttonBackgroundColor = VSColors.vsGray900, double horizontalMargin = 16})
// A `VirtusizeInPageStandard` widget with a default `VSColors.vsGray900` button background color and a default horizontal margin of `16`
VirtusizeInPageStandard(product: _product)

// A `VirtusizeInPageStandard` widget with a `Colors.amber` button background color and a horizontal margin of `32`
VirtusizeInPageStandard(
product: _product,
buttonBackgroundColor: Colors.amber,
horizontalMargin: 32
)
copied to clipboard


B. Design Guidelines


Default Designs
There are two default design variations.



Teal Theme
Black Theme











Layout Variations
Here are some possible layouts



1 thumbnail + 2 lines of message
2 thumbnails + 2 lines of message








1 thumbnail + 1 line of message
2 animated thumbnails + 2 lines of message









Recommended Placement

Near the size table
In the size info section




UI customization

You can:

change the background color of the CTA button as long as it passes WebAIM contrast test.
change the width of InPage, so it fits your application width.


You cannot:

change interface components such as shapes and spacing.
change the font.
change the CTA button shape.
change messages.
change or hide the box shadow.
hide the footer that contains VIRTUSIZE logo and Privacy Policy text link.





(3) InPage Mini
This is a mini version of InPage that you can place in your application. The discreet design is suitable for layouts where customers are browsing product images and size tables.
A. Usage


VirtusizeInPageMini.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.Black, double horizontalMargin = 16})
Create a VirtusizeInPageMini widget with the default Virtusize style and the ability to change the horizontal margin, using the same VirtusizeClientProduct object that you have passed to the VirtusizeSDK.instance.loadVirtusize function
// A `VirtusizeInPageMini` widget with default `Black` style and a default horizontal margin of `16`
VirtusizeInPageMini.vsStyle(product: _product)

// A `VirtusizeInPageMini` widget with `Teal` style and a default horizontal margin of `16`
VirtusizeInPageMini.vsStyle(
product: _product,
style: VirtusizeStyle.Teal
)
copied to clipboard
create a VirtusizeInPageMini widget with the ability to change the background color and the horizontal margin:


VirtusizeInPageMini({required VirtusizeClientProduct product, Color backgroundColor = VSColors.vsGray900, double horizontalMargin = 16})
// A `VirtusizeInPageMini` widget with a default `VSColors.vsGray900` background color and a default horizontal margin of `16`
VirtusizeInPageMini(product: _product)

// A `VirtusizeInPageMini` widget with a `Colors.blue` background color and a default horizontal margin of `16`
VirtusizeInPageMini(
product: _product,
backgroundColor: Colors.blue
)
copied to clipboard


B. Design Guidelines


Default designs
There are two default design variations.



Teal Theme
Black Theme











Recommended Placements



Underneath the product image
Underneath or near the size table











Default Fonts

Japanese

Noto Sans CJK JP
(Message) Text size: 12
(Button) Text size: 10


Korean

Noto Sans CJK KR
(Message) Text size: 12
(Button) Text size: 10


English

Roboto for Android and San Francisco for iOS
(Message) Text size: 14
(Button) Text size: 12





UI customization

You can:

change the background color of the bar as long as it passes WebAIM contrast test.


You cannot:

change the font.
change the CTA button shape.
change messages.





The Order API #
The order API enables Virtusize to show your customers the items they have recently purchased as part of their Purchase History, and to use those items to compare with new items they want to buy.
1. Initialization
Ensure that the user ID is set before sending orders to Virtusize. You can set up the user ID:
while setting the Virtusize parameters using VirtusizeSDK.instance.setVirtusizeParams
or
anywhere before calling the VirtusizeSDK.instance.sendOrder function
// Use the `VirtusizeSDK.instance.setVirtusizeParams` to set the user ID
VirtusizeSDK.instance.setVirtusizeParams(
apiKey: '15cc36e1d7dad62b8e11722ce1a245cb6c5e6692',
userId: '123',
...
);

// Use the `VirtusizeSDK.instance.setUserId` before sending an order
VirtusizeSDK.instance.setUserId("123456");
copied to clipboard
2. Create a VirtusizeOrder object for order data
The VirtusizeOrder object gets passed to the VirtusizeSDK.instance.sendOrder function, and has the following attributes:
Note: * means the argument is required
VirtusizeOrder



Argument
Type
Example
Description




externalOrderId*
String
"20200601586"
The order ID provided by the client


items*
List<VirtusizeOrderItem>
See the table below
A list of the order items.



VirtusizeOrderItem



Argument
Type
Example
Description




externalProductId*
String
"A001"
The external product ID provided by the client. It must be unique for each product.


size*
String
"S", "M", etc.
The name of the size


sizeAlias
String
"Small", "Large", etc.
The alias of the size is added if the size name is not identical to the one from the product page


variantId
String
"A001_SIZES_RED"
The variant ID is set on the product SKU, color, or size (if there are several options)


imageURL*
String
"http://images.example.com/coat.jpg"
The image URL of the item


color
String
"RED", "R', etc.
The color of the item


gender
String
"W", "Women", etc.
An identifier for the gender


unitPrice*
double
5100.00
The product price that is a double number with a maximum of 12 digits and 2 decimals (12, 2)


currency*
String
"JPY", "KRW", "USD", etc.
Currency code


quantity*
int
1
The number of items purchased. If it's not passed, it will default to 1


url
String
"http://example.com/products/A001"
The URL of the product page. Please make sure this is a URL that users can access



Example
VirtusizeOrder order = VirtusizeOrder(
externalOrderId: "20200601586",
items: [
VirtusizeOrderItem(
externalProductId: "A001",
size: "L",
sizeAlias: "Large",
variantId: "A001_SIZEL_RED",
imageURL: "http://images.example.com/products/A001/red/image1xl.jpg",
color: "Red",
gender: "W",
unitPrice: 5100.00,
currency: "JPY",
quantity: 1,
url: "http://example.com/products/A001"
)
]
);
copied to clipboard
3. Send an Order
Call the VirtusizeSDK.instance.sendOrder function when the user places an order.
The onSuccess and onError callbacks are optional.
VirtusizeSDK.instance.sendOrder(
order: order,
// The `onSuccess` callback is optional and is called when the app has successfully sent the order
onSuccess: (sentOrder) {
print("Successfully sent the order $sentOrder");
},
// The `onError` callback is optional and gets called when an error occurs while the app is sending the order
onError: (error) {
print(error);
}
);
copied to clipboard
Example #
https://github.com/virtusize/virtusize_flutter_sdk/tree/main/example
License #
Copyright (c) 2021-present Virtusize CO LTD (https://www.virtusize.jp)