virtusize_flutter_sdk 1.0.1

Virtusize SDK for Flutter. This SDK helps clients to integrate Virtusize’s size and fit service into their Flutter applications for Android & iOS.

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'
  

• Android 5.0+ (API Level 21+)

  Set the minSdkVersion to at least 21 in android/app/build.gradle:

  android {
    defaultConfig {
        minSdkVersion 21
    }
  }
  

Usage

1. Add virtusize_flutter_sdk as a dependency in your pubspec.yaml file.

   dependencies:
     virtusize_flutter_sdk: ^1.0.1
   

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

Setup

1. Android

1. 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>
   

2. 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() {
   }
   

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());
}

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);
}

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);
});

(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');
            }
       )
    );
}

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")
  )
  

  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))
      )
  )
  

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⚠️

1. InPage cannot be implemented together with the Virtusize button. Please pick either InPage or Virtusize button for your online shop.
2. 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
  )
  

  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
  )
  

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
  )
  

  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
  )
  

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");

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"
        )
    ]
);

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);
    }
);

Example

https://github.com/virtusize/virtusize_flutter_sdk/tree/main/example

License

Copyright (c) 2021-present Virtusize CO LTD (https://www.virtusize.jp)