本書では現在Unityアプリケーションで使われている0.0.21以前のVRoid SDKを0.1.0へアップグレードする手順について示します。

1. 0.0.21以前から0.1.0へのアップデート

変更点についてはCHANGELOGを参照してください。

1.1 名前空間の変更

0.1.0から VRoidSDK VRoidSDK.OAuth などの名前空間が変更・整理されました。従来まで同じ名前空間に所属していた機能でもより細分化され別のところに移動されています。

特に、0.0.21まで実装されていた Authentication HubApi HubModelDeserializer は0.1.0でDeprecatedになるので、 Pixiv.VroidSdk.Unity.Oauth.Legacy Pixiv.VroidSdk.Api.Legacy 名前空間の下に移動されました。従来通り利用する場合はそれぞれ適切な名前空間に変更してください。

1.2 HubApiとHubModelDeserializerの初期化

0.0.21以前では Authentication による認可した後にそのまま HubApi HubModelDeserializer の利用ができましたが、0.1.0では実行前に初期化処理が必要になりました。 HubModelDeserializer については HubApi の初期化時に同時に初期化されるため明示的に初期化メソッドを呼び出す必要はありません。

class Hoge : MonoBehaviour
{
    void Start()
    {
      Authentication.Instance.Init(_sdkConfiguration.AuthenticateMetaData);

			// 0.1.0からHubApiの初期化が必要
      // 内部で自動的に `HubModelDeserializer.Instance` の初期化も行われる
      HubApi.Initialize(Authentication.Instance.Client, _sdkConfiguration.GetConfig());

			// 認可
      Authentication.Instance.AuthorizeWithExistAccount(...);

			HubApi.GetAccountCharacterModels(
			    count: 10,
			    onSuccess: (List<CharacterModel> characterModels) => {
							HubModelDeserializer.Instance.LoadCharacterAsync(
							    characterModel: characterModels[0],
							    onDownloadProgress: (float progress) => {
							    },
							    onLoadComplete: (GameObject characterObj) => {
											characterObj.transform.parent = this.transform;
							    },
							    onError: (Exception error) => {
							    }
							);
					},
			    onError: (ApiErrorFormat errorFormat) => { /* 通信エラーなどのエラーが発生した時の処理 */ }
			);
    }
}

1.3 暗号化パスワードの設定

0.0.21以前はモデルの暗号化に使うパスワードを特に指定せずとも使えましたが、0.1.0からはモデルのデータ保護を強化するためにアプリごとに1文字以上の任意の文字列をパスワードに設定していただく必要があります。

このパスワードは HubModelDeserializer.Instance.LoadCharacterAsync や新しいモデル読み込み機能で引数に渡すことになります。

HubApi.GetAccountCharacterModels(
    count: 10,
    onSuccess: (List<CharacterModel> characterModels) => {
				HubModelDeserializer.Instance.LoadCharacterAsync(
				    characterModel: characterModels[0],
						encryptPassword: "PASSWORD_FOR_YOUR_APP", // 0.1.0より暗号化パスワードを追加
				    onDownloadProgress: (float progress) => {
				    },
				    onLoadComplete: (GameObject characterObj) => {
								characterObj.transform.parent = this.transform;
				    },
				    onError: (Exception error) => {
				    }
				);
		},
    onError: (ApiErrorFormat errorFormat) => { /* 通信エラーなどのエラーが発生した時の処理 */ }
);

1.4 レスポンスのDataModelが参照型になるので追従

0.0.21以前ではVRoid Hubからのレスポンスを構造体(値型)として受けていましたが、0.1.0からは全て参照型で統一されました。Null許容型を利用しているといった値型であることを期待したコードはコンパイルエラーになるので修正が必要になります。

using Pixiv.VroidSdk.Api.DataModel;

public class Model : ApplicationModel
{
	// Null許容型はコンパイルエラー
-    public Account? CurrentUser { get; set; }
+    public Account CurrentUser { get; set; }

    public Model()
    {
        CurrentUser = null;
    }
}

1.5 モデルのマテリアル情報のレスポンス修正

ダウンロード前にモデルのプロパティ情報(ボーン数・メッシュ数・マテリアル情報など)を取得している場合、0.1.0からマテリアルの拡張情報である GltfMaterial#extensions の型が変更されました。0.0.21以前は Dictionary<string, object> でしたが、 GltfMaterialExtension になっております。

これにより KHR_materials_unlit が存在するかの判定方法が変わります。


public override void Init(GltfMaterial baseData)
{
    if (baseData.extensions != null)
    {
         // 0.0.21以前はDictionaryを返す
-        foreach (var x in baseData.extensions)
-        {
-            stringBuilder.AppendLine("\\t" + x.Key + "：" + x.Value);
-        }
   			 // 0.1.0からはKHR_materials_unlitをメンバ変数に持ったオブジェクトがextensionsになる
+        if(baseData.extensions.KHR_materials_unlit != null)
+				 {
+						stringBuilder.AppendLine("\\t KHR_materials_unlit：{}");
+				 }
    }
}

2. 新機能・新しいAPIの利用

VRoid SDK 0.1.0から基本機能を利用するインターフェースが大きく変更されました。

0.1.0から追加された新機能は基本的に新しく用意したこのインターフェースを用いて実装することが可能です。

従来までの Authentication HubApi HubModelDeserializer と新しく用意されたものは併用することができないのでご注意ください。

2.1 認可の仕組みの変更

0.1.0からは従来の Authentication をつかった認可フローがDeprecatedになりました。 0.1.0からは 新しく用意されたPixiv.VroidSdk.OauthProvider と Pixiv.VroidSdk.Oauth.Client 、 Pixiv.VroidSdk.BrowserProvider を使って認可を行うことになります。

また、SDKConfigurationを使ったアプリケーションの情報の設定もあわせてDeprecatedになりました。今後はアプリケーション管理ページから credential.json.bytes をダウンロードしていただきそれを設定することになります。

class Login : MonoBehaviour
{
    void Start()
    {
				// 通信に使うThreadContext
				var context = SynchronizationContext.Current;
				// ダウンロードしたcredential.json.bytesを読み込み
				var credential = Resources.Load<TextAsset>("credential.json");
				// 設定に使うアプリ情報
				var credentialJson = credential.text;
				// 認可に使うConfigの作成
				var config = OauthProvider.LoadConfigFromCredential(credentialJson);
				// OAuthの認可を扱うClientを作成する
	      var oauthClient = OauthProvider.CreateOauthClient(config, context);
				// ログインに使うBrowserを作成
	      var browser = BrowserProvider.Create(oauthClient, config);
				// ローカルにアカウントファイル保存済みかつ期限が切れてない
				var isLoggedIn = oauthClient.IsAccountFileExist() && !oauthClient.IsAccessTokenExpired();				
				// ログイン
				if (!isLoggedIn)
				{
						// すでに認可済みだが期限切れの場合は再認可。 
						// そうでなければブラウザを開いて認可フローを開始する。
						oauthClient.Login(
							browser,
							(account) => { /*ログイン成功時*/ },
					    (error) => { /*ログイン失敗時*/ }
						);
				}
    }
}

2.2 新しいAPI利用のインターフェース

0.1.0からVRoidHubの機能を使う HubApi はDeprecatedになりました。認可済みの Pixiv.VroidSdk.Oauth.Client を利用した新しいAPIオブジェクトを利用することになります。

class Login : MonoBehaviour
{
		private Account _account;

    void Start()
    {
				...
	      var oauthClient = OauthProvider.CreateOauthClient(config, context);

				// 認可を行うClientを使ってDefaultApiを作成
				var defaultApi = new DefaultApi(oauthClient);
				// ハートスコープのAPIはHeartApiを使う
				// var heartApi = new HeartApi(oauthClient);

				// ログイン
				if (!isLoggedIn)
				{
						// すでに認可済みだが期限切れの場合は再認可。 
						// そうでなければブラウザを開いて認可フローを開始する。
						oauthClient.Login(
							browser,
							(account) => {
								// 認可完了済みならAPI機能が使える
								 defaultApi.GetAccount((ac) => _account = ac, (error) => { });
							},
					    (error) => { /*ログイン失敗時*/ }
						);
				}
    }
}

2.3 モデルの読み込み

0.1.0からモデルの読み込みに利用した HubModelDeserializer はDeprecatedになりました。

0.1.0からはモデルの利用・キャッシュ保存管理に ModelLoader を利用することになります。

	oauthClient.Login(
		browser,
		(account) => {
			// モデル読み込みに使うModelLoaderを初期化
			ModelLoader.Initialize(
				config,                  // Credentialから作成したConfig
				defaultApi,              // 認可済みのAPI
				"PASSWORD_FOR_YOUR_APP", // モデル暗号化のパスワード
				10,                      // モデルの最大キャッシュ数
				context                  // メインスレッドのSynchronizationContext
			);

			defaultApi.GetAccountCharacterModels(10, (models) => {
				// モデル読み込みの開始
				ModelLoader.LoadVrm(
					models[0],  // 読み込むモデル
					(gameObject) => {
						// 読み込み完了後のコールバック
						gameObject.transform.parent = this.transform;
					},
					(progress) => {
						// 読み込み中の進捗コールバック
					},
					(error) => {
						// エラー発生時のコールバック
					},
					(VRMData vrmData) => {
						// vrmDataからVRMImporterContextを作成する
						return new VRMImporterContext(vrmData);
					}
				);
			}, (error) => { });
		},
    (error) => { /*ログイン失敗時*/ }
	);

2.4 通信バックエンドの切り替え

0.1.0から通信に使うライブラリを従来通りのUnityWebRequestかHttpClientを使ったものを選択できるようになりました。

Authentication は従来通りUnityWebRequestをデフォルトで採用

Oauth.Client を作るとHttpClientで動作します。

これは初期化段階で選択することが可能です。

// Authenticationの第二引数で指定可能
Authentication.Instance.Init(
	metaData,
	new HttpClientDriver(SynchronizationContext.Current)
);

// OauthProviderからClientを作るときに第二引数で指定可能
var oauthClient = OauthProvider.CreateOauthClient(
	config,
	new UnityWebRequestDriver(SynchronizationContext.Current)
);

2.5 Loopback interface redirectによるデスクトップアプリでのOAuth認可

0.1.0からOauthの認可フローにLoopback interface redirectによる認可コード受け取りの仕組みを導入しました。

従来はデスクトップアプリで認可を行う場合、手動で認可コードをブラウザからコピーしてアプリケーションにペーストする仕様でしかVRoid Hubと連携ができませんでしたが、Loopback interface redirectではそれが不要になります。ブラウザ上でログインして認可ボタンを押すだけで連携が完了します。

この仕組みは「2.1 認可の仕組みの変更」の Pixiv.VroidSdk.OauthProvider と Pixiv.VroidSdk.Oauth.Client 、 Pixiv.VroidSdk.BrowserProvider を使い実装が行えます。Deprecateになった従来のAPIでは利用できないのでご注意ください。

2.5.1 リダイレクトURIに http://127.0.0.1 を設定する

2.5.1.1 VRoid Hubアプリケーション作成画面のリダイレクトURI設定

2.5.1.1 VRoid Hubアプリケーション作成画面のリダイレクトURI設定

2.5.2 アプリケーション管理画面からcredential.json.bytesをダウンロード

デスクトップ向けリダイレクトURIを http://127.0.0.1 で設定しダウンロードしてください。

従来通りの認可コードを貼り付けるログイン方式を採用したい場合はurn:ietf:wg:oauth:2.0:oob を設定し作成してください。

2.5.2.2 VRoid Hubアプリケーション作成画面Credential作成モーダル

2.5.2.2 VRoid Hubアプリケーション作成画面Credential作成モーダル

2.5.3 「2.1 認可の仕組みの変更」を参考に認可を実行する

「2.1 認可の仕組みの変更」をもとにConfigを設定する。

class Login : MonoBehaviour
{
    void Start()
    {
				...
				// 認可に使うConfigの作成
				// iOS/Androidの場合はURLSchemeを使った自動ログイン
				// Windows/macOSの場合はLoopback interface redirectでのログインになる
        var credential = Resources.Load<TextAsset>("credential.json");
				var config = OauthProvider.LoadConfigFromCredential(credential.text);
				...
    }
}