Skip to content

README-JP.md

Latest commit

 

History

History
674 lines (450 loc) · 33.2 KB

README-JP.md

File metadata and controls

674 lines (450 loc) · 33.2 KB

Virtusize Flutter SDK

pub package

English

A Flutter plugin that wraps Virtusize Native SDKs for Android & iOS.

Table of Contents

はじめに

バーチャサイズは商品詳細ページにあるサイズ情報を元に、アイテムのサイズ感をシルエット化しお客様が購入されたい商品をオンライン上で比較しやすいようサポートをしてます。

詳しくはこちらをご確認ください。https://www.virtusize.com

実装作業を始められる前にバーチャサイズの御社ご担当者に「API キー」と「ストア名」をお訊ねください。

こちらは Flutter用実装ガイドです。 Webの実装はhttps://developers.virtusize.comをご確認ください。

対応バージョン

  • iOS 14.0+

    iOS バージョン14.0以上をご利用されているかios/Podfileにてご確認ください。

    platform :ios, '14.0'

  • Android 5.0+ (API Level 21+)

    android/app/build.gradle を 21以上をご利用されているかご確認の上、minSdkVersion を設定ください。

    android {
  defaultConfig {
      minSdkVersion 21
  }
}

使用方法

  1. pubspec.yaml fileにvirtusize_flutter_sdkを追加。

    dependencies:
  virtusize_flutter_sdk: ^2.2.10

  2. flutter pub get をターミナルで実行または IntelliJ / Android Studio 内Pub getをクリックください。

セットアップ

1. Android

(1) Proguardを使用している場合は、以下のルールをProguardルールファイルに追加してください：

-keep class com.virtusize.android.**

(2) SDKでVirtusizeのWebViewをFragment内で開けるようにするには、android/app/src/main/MainActivityでFlutterActivityの代わりにFlutterFragmentActivityを継承してください。

```diff
- import io.flutter.embedding.android.FlutterActivity
+ import io.flutter.embedding.android.FlutterFragmentActivity

- class MainActivity: FlutterActivity() {
+ class MainActivity: FlutterFragmentActivity() {
}
```

2. Flutter

(1) はじめに

runAppを実行する前に、VirtusizeSDK.instance.setVirtusizeParams関数を使用してVirtusizeパラメーターを設定します。

import 'package:virtusize_flutter_sdk/virtusize_flutter_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await 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],
    // By default, Virtusize does not show SNS buttons
    showSNSButtons: true,
    // Target the specific environment branch by its name
    branch: 'branch-name',
  );

  runApp(MyApp());
}

可能な引数構成を次の表に示します。

データ形式 タイプ 例 説明 必須設定
apiKey String 'api_key' 担当者が用意した「API キー」遠設定ください。 Yes
userId String '123' ユーザーがクライアントのアプリにログインしている場合、クライアントから渡されます。 Yes,OrderAPIが使用されている場合。
env VSEnvironment VSEnvironment.staging 設定環境は、統合を実行している地域のいずれか
VSEnvironment.staging, VSEnvironment.global, VSEnvironment.japan または VSEnvironment.korea。		 No. デフォルトでは、Virtusize環境は次のように設定されますVSEnvironment.global。
language VSLanguage VSLanguage.jp 統合がロードされる初期言語を設定します。可能な値は次のとおりです。
VSLanguage.en, VSLanguage.jp および VSLanguage.kr		 No. デフォルトでは、初期言語はVirtusize環境に基づいて設定されます。
showSGI bool true ユーザーが生成したアイテムをワードローブに追加する方法として、SGIを取得の上、SGIフローを使用するかどうかを決定します。 No. デフォルトではShowSGIはfalseに設定されています。
allowedLanguages List<VSLanguage> [VSLanguage.en, VSLanguage.jp] ユーザーが言語選択ボタンより選択できる言語。 特になし。デフォルトでは、英語、日本語、韓国語など、表示可能なすべての言語が表示されるようになっています。
detailsPanelCards List<VSInfoCategory> [VSInfoCategory.generalFit, VSInfoCategory.brandSizing] 商品詳細タブに表示する情報のカテゴリ。表示可能カテゴリは以下：
VSInfoCategory.modelInfo, VSInfoCategory.generalFit, VSInfoCategory.brandSizing およびVSInfoCategory.material		 No. デフォルトでは、商品詳細タブに表示可能なすべての情報カテゴリが表示されます。
showSNSButtons bool true 統合時にユーザーにSNSボタンを表示するかどうかを決定します。 No.デフォルトでは、統合時にSNSボタンは無効になっています。
branch String 'branch-name' 特定の環境ブランチを対象とします。 デフォルトでは、本番環境が対象になります。staging を指定するとステージング環境が対象になります。<branch-name> を指定すると、特定のブランチが対象になります。
showPrivacyPolicy Boolean showShowPrivacyPolicy: true プライバシー ポリシーをユーザーに表示するかどうかを制御します。 No. デフォルトでは、プライバシー ポリシーが表示されます。

(2) Virtusizeにて商品詳細をロードする

商品詳細ページウィジェットのinitStateで、VirtusizeSDK.instance.loadVirtusizeを使用してVirtusizeウィジェットにデータを入力する必要があります。

  • VirtusizeClientProductオブジェクトを作成して以下情報を設定してください。
    • Virtusizeサーバーで商品詳細をロードするために使用されるexernalId
    • 商品画像のimageURL
  • VirtusizeClientProductオブジェクトをVirtusizeSDK.instance.loadVirtusize関数に渡します。
/// 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);
}

ユーザーが同じ画面を表示しているときに製品を別の製品に更新する場合は、別のVirtusizeClientProductオブジェクトを_productに割り当て、setState()内のVirtusizeSDK.instance.loadVirtusizeを使用して製品を再読み込みし、ウィジェットを再構築します。

setState(() {
    _product = VirtusizeClientProduct(
        externalProductId: 'vs_pants',
        imageURL: 'https://www.image.com/goods/12345.jpg'
    );
    VirtusizeSDK.instance.loadVirtusize(_product);
});

(3) VirtusizeMessageHandlerを実装する（オプション）

VirtusizeMessageListenerを登録して、VirtusizeからのイベントとProductDataCheckの結果を確認できます。

VirtusizeSDK.instance.setVirtusizeMessageListener関数のすべての引数はオプションです。

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

こちらが翻訳済みの日本語バージョンです（Markdown形式を維持しています）：

3. SNS認証を有効にする

1. Android

SNS認証フローでは、Chrome Custom Tabを開いてユーザーがSNSアカウントでログインできるウェブページを読み込みます。ログインのレスポンスをChrome Custom Tabからアプリに返すためには、カスタムURLスキームを定義する必要があります。

AndroidManifest.xml ファイルを編集し、インテントフィルターおよびカスタムURLスキーム用の <data> タグを追加してください。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your-company.your-app">

    <activity android:name="com.virtusize.android.auth.views.VitrusizeAuthActivity"
        android:launchMode="singleTask" android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />

            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />

            <data android:host="sns-auth" android:scheme="com.your-company.your-app.virtusize" />
        </intent-filter>
    </activity>

</manifest>

❗重要

  1. URLのホストは sns-auth である必要があります。
  2. URLスキームはアプリのパッケージID（com.your-company.your-app）で始まり、.virtusizeで終わる必要があります。また、スキームはすべて小文字で定義してください。

2. iOS

SNS認証フローでは、SFSafariViewControllerに切り替えて、ユーザーがSNSアカウントでログインできるウェブページを読み込みます。ログインのレスポンスをSFSafariViewControllerからアプリに返すためには、カスタムURLスキームを定義する必要があります。

(1) URLタイプの登録

Xcodeで、プロジェクトの Info タブをクリックし、URL Types を選択します。

新しいURLタイプを追加し、URLスキームと識別子を com.your-company.your-app.virtusize に設定してください。

Screen Shot 2021-11-10 at 21 36 31

(2) アプリケーションのコールバックハンドラーを設定

AppDelegate の application(_:open:options) メソッドを実装してください：

override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
      NotificationCenter.default.post(
        name: Notification.Name("VirtusizeFlutterHandleURL"),
        object: url
      )
      
      return super.application(app, open: url, options: options)
  }

❗重要

  1. URLタイプには、アプリのバンドルIDを含め、.virtusizeで終わる必要があります。
  2. 複数のアプリアイデンティティ（ターゲット）がある場合は、それぞれにURLタイプを追加してください。

Virtusizeウィジェット実装

SDKをセットアップした後、Virtusizeウィジェットを追加して、顧客が理想的なサイズを見つけられるようにします。

Virtusize SDKはユーザーが使用するために2つの主要なUIコンポーネントを提供します。:

1. バーチャサイズ・ボタン（Virtusize Button）

(1) はじめに

VirtusizeButtonはこのSDKの中でもっとシンプルなUIのボタンです。ユーザーが正しいサイズを見つけられるように、ウェブビューでアプリケーションを開きます。

(2) デフォルトスタイル

SDKのVirtusizeボタンには2つのデフォルトスタイルがあります。

Teal Theme Black Theme
img img

もしご希望であれば、ボタンのスタイルもカスタマイズすることができます。

(3) 使用方法

  • VirtusizeButton.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.black, Widget child})

    デフォルトのVirtusizeスタイルで、VirtusizeSDK.instance.loadVirtusize関数に渡したものと同じVirtusizeClientProductオブジェクトを使用してVirtusizeButtonウィジェットを作成します。

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

または、カスタムボタンウィジェットを使用してVirtusizeButtonウィジェットを作成します。

  • 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. バーチャサイズ・インページ（Virtuzie InPage）

(1) はじめに

Virtusize InPageは、サービスのスタートボタンのように動作するボタンです。こちらは、ユーザーが一目で適切なサイズがわかるフィッティングガイドとしても機能します。

InPage types

Virtusize SDKには2種類のInPageがあります。

InPage Standard InPage Mini
InPageStandard InPageMini

⚠️注意⚠️

  1. InPageをVirtusizeボタンと一緒に実装することはできません。オンラインショップのInPageまたはVirtusizeボタンを選択してください。
  2. InPage Miniは、常にInPageStandardと組み合わせて使用する必要があります。

(2) インページ・スタンダード（InPage Standard）

A. 使用方法

  • VirtusizeInPageStandard.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.black, double horizontalMargin = 16})

    VirtusizeSDK.instance.loadVirtusize関数に渡した同じVirtusizeClientProductオブジェクトを使用して、デフォルトのVirtusizeスタイルとhorizontal marginを変更する機能を備えたVirtusizeInPageStandardウィジェットを作成します。

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

または、ボタンのbackground colorとhorizontal marginを変更する機能を備えたVirtusizeInPageStandardウィジェットを作成します。

  • 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. デザインガイドライン
  • デフォルトのデザイン

    デフォルトのデザインバリエーションは2つあります。

    Teal Theme Black Theme
    InPageStandardTeal InPageStandardBlack
  • レイアウトのバリエーション

    考えられるレイアウトは次のとおりです。

    1 thumbnail + 2 lines of message 2 thumbnails + 2 lines of message
    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
    1 thumbnail + 1 line of message 2 animated thumbnails + 2 lines of message
  • 推奨される配置
    • サイズテーブルの近く
    • サイズ情報内

    img

  • UIのカスタマイズ
    • できる事
      • WebAIMコントラストテストを合格した色に限り、CTAボタンの背景色を変更できます。
      • アプリケーションの幅と一致するようInPageの幅を変更できます。
    • できない事
      • 形やスペーシングなどのインターフェイスコンポーネントの変更。
      • フォントの変更。
      • CTAボタンの形の変更。
      • メッセージの変更。
      • インページボックス影デザインの変更または非表示切り替え。
      • VIRTUSIZEロゴとプライバシーポリシーのテキストリンクを含むフッター非表示切り替え。

(3) インページ・ミニ（InPage Mini）

これは、アプリケーションに配置できるInPageのミニバージョンです。目立たないデザインは、顧客が商品の画像やサイズ表を閲覧しているレイアウトに適しています。

A. 使用方法

  • VirtusizeInPageMini.vsStyle({required VirtusizeClientProduct product, VirtusizeStyle style = VirtusizeStyle.black, double horizontalMargin = 16})

    VirtusizeSDK.instance.loadVirtusize関数に渡したものと同じVirtusizeClientProductオブジェクトを使用して、デフォルトのVirtusizeスタイルとhorizontal marginを変更する機能を備えたVirtusizeInPageMiniウィジェットを作成します。

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

または、background colorとhorizontal marginを変更する機能を備えたVirtusizeInPageMiniウィジェットを作成します。

  • 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. デザインガイドライン
  • デフォルトのデザイン

    デフォルトのデザインバリエーションは2つあります。

    Teal Theme Black Theme
    InPageMiniTeal InPageMiniBlack
  • 推奨される配置
    Underneath the product image Underneath or near the size table
    img img
  • デフォルトのフォント
    • 日本語
      • Noto Sans CJK JP
      • (Message) Text size: 12
      • (Button) Text size: 10
    • 韓国語
      • Noto Sans CJK KR
      • (Message) Text size: 12
      • (Button) Text size: 10
    • 英語
      • Roboto for Android and San Francisco for iOS
      • (Message) Text size: 14
      • (Button) Text size: 12
  • UIのカスタマイズ
    • できる事
    • できない事
      • フォントの変更。
      • CTAボタンの形変更。
      • メッセージの変更。

Order API

注文APIを使用すると、Virtusizeは、購入履歴の一部として最近購入したアイテムを顧客に表示し、それらのアイテムを使用して、購入したい新しいアイテムと比較することができます。

1. はじめに

Virtusizeに注文を送信する前に、ユーザーIDが設定されていることを確認してください。以下にてユーザーIDを設定できます：

VirtusizeSDK.instance.setVirtusizeParamsを使用してVirtusizeパラメーターを設定している間

または

VirtusizeSDK.instance.sendOrder関数を呼び出す前の任意の場所

// 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. 注文データのVirtusizeOrder オブジェクトを作成

VirtusizeOrderオブジェクトはVirtusizeSDK.instance.sendOrder関数に渡され、次の属性があります。

注：*は引数が必要であることを意味します。

VirtusizeOrder

データ形式 タイプ 例 説明
externalOrderId* String "20200601586" 御社にてご用意いただいたオーダーID
items* List<VirtusizeOrderItem> See the table below オーダー商品リスト

VirtusizeOrderItem

データ形式 タイプ 例 説明
externalProductId* String "A001" 各商品ユニークIDをご利用ください
size* String "S", "M", etc. サイズ名称
sizeAlias String "Small", "Large", etc. サイズ名が商品ページのものと同一でない場合は、サイズのエイリアスが追加されます
variantId String "A001_SIZES_RED" バリアントIDは、製品のSKU、色、またはサイズに設定されます（複数のオプションがある場合）
imageURL* String "http://images.example.com/coat.jpg" 商品画像URL
color String "RED", "R', etc. 色
gender String "W", "Women", etc. 性別
unitPrice* double 5100.00 最大12桁と小数点以下2桁の2桁の製品価格（12、2）
currency* String "JPY", "KRW", "USD", etc. 通貨コード
quantity* int 1 購入したアイテム数。共有がなかった場合、デフォルトで1になります。
url String "http://example.com/products/A001" 商品ページのURL。これがユーザーがアクセスできるURLであることを確認してください。

サンプル例

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. 注文情報の送信

ユーザーが注文するときに、VirtusizeSDK.instance.sendOrder関数を呼び出します。

onSuccessおよびonErrorコールバックはオプションです。

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)