移行ガイド

SDK X UnityプラグインはハイブリッドSDKであり、ダウンタイムがなく、またアプリのアップデートを行うことなくアップデートの大半を無線を介してエンドユーザーへと送信することができるため、イノベーションを素早く展開することができます。この移行ガイドでは、HelpshiftのレガシーSDK UnityプラグインからSDK X Unityプラグインへの移行を行うために必要となる手順について説明します。

SDK X Unityプラグインへの移行を行うための手順

レガシーSDK UnityプラグインからSDK X Unityプラグインへの移行

#1

移行のサポート状況を確認する

移行ガイドを一通り確認する

#2

SDK X Unityプラグインにアップデートする

コードや機能を順を追って移行する

#3

移行のテストを行う

機能の検証を行う

非対応の機能

現時点で以下のAPI/機能を使用している場合には、SDK Xへの移行の延期を推奨しています -

• ガイド付きの問題提出
• 問題に関する記述の長さの最小値設定
• SDKのUI文字列のカスタマイズ
• ライトテーマとダークテーマの切り替え

これらの機能はまだ開発中であり、2022年のロードマップに追加される可能性があります。上記のAPI/機能に関しては、support@helpshift.comまでお問い合わせください。

対応するSDKのバージョン

移行が成功すれば、SDKのあるバージョンから別のバージョンへと移行してもユーザーのデータとチャット履歴は保持されます。バージョン4以上のSDK UnityプラグインからSDK X Unityプラグインへの移行がサポートされています。

注意

3.xより前のバージョンのSDK Unityプラグインからの移行

3.xより前のバージョンのSDK Unityプラグインからの移行はサポートされていません。3.xより前のバージョンからSDK X Unityプラグインへと移行した場合、SDK Xは正常に機能しますが、ログイン済みユーザーの情報は失われ、新しいデフォルトのユーザーが作成されます。現在のユーザーをもう一度ログインさせることは可能ですが、そのユーザーに対応するデータは移行されません。Helpshiftのシステムでは、新規のユーザーとして扱われます。

Helpshiftの依存関係を更新する

必要条件

• Unity 2018.1.0以上。
• Xcode 12.0以上。

統合

• 既存の Helpshift unitypackageの内容をプロジェクトから削除してください。
• サポートSDKパッケージをインポートする前に、以下のディレクトリがプロジェクトから削除されていることをご確認ください。
  • Assets/Helpshift/
  • Assets/Plugins/Android/helpshift-plugin-resources.aar
  • Assets/Plugins/Android/helpshift-plugin-wrapper
  • Assets/Plugins/Android/Helpshift.aar
• プロジェクトにHelpshift SDK Xを追加するには、こちらの手順にしたがってください。

コードの変更

Helpshiftの依存関係を更新した後にUnityからXcodeプロジェクトのビルドを試みると、コンパイルエラーが発生します。これは、レガシーSDKとSDK Xの間で一部のAPIのメソッド名とシグネチャが変更されていることが原因となっています。

Helpshiftのinstall呼び出し

既存のHelpshiftインストール呼び出しを削除し、以下のように置き換えてください。

using Helpshift;
...
public class MyGameControl : MonoBehaviour
{
    private HelpshiftSdk _support;
    ...
    void Awake() {
        _support = HelpshiftSdk.GetInstance();
        var configMap = new Dictionary<string, object>();
        _support.Install(platformId, domainName, configMap);
    }
    ...
}

XcodeからObjective-Cを利用してSDKを初期化する場合は、こちらの手順をご参照ください。 詳細については、SDK X Unityプラグインのはじめにガイドをご参照ください。

Helpshiftのインストール呼び出しの構成

インストール構成辞書キーへのマッピングは、以下の通りです。

レガシーSDK Unityプラグインのインストール構成辞書キー	SDK X Unityプラグインのインストール構成辞書キー
HelpshiftSdk.ENABLE_LOGGING	HelpshiftSdk.ENABLE_LOGGING
HelpshiftSdk.ENABLE_IN_APP_NOTIFICATION	HelpshiftSdk.ENABLE_INAPP_NOTIFICATION

その他の非推奨となった構成はすべて削除されており、もうサポートされていません。インストール構成の詳細については、構成ガイドをご参照ください。

HelpshiftのConversation APIとFAQ API

APIのシグネチャは変更されています。既存のAPI呼び出しを、以下の新しいものに更新してください。

レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
showConversation(configMap)	ShowConversation(configMap)
showFAQs(configMap)	ShowFAQs(configMap)
showFAQSection(sectionPublishId, configMap)	ShowFAQSection(sectionId,configMap)
showSingleFAQ(questionPublishId, configMap)	ShowSingleFAQ(faqId,configMap)
タグによるFAQのフィルタリング	現在対応していません
ガイド付きの問題提出	現在対応していません

Conversation APIとFAQ APIの詳細については、Helpshift APIガイドをご参照ください。

Conversation APIとFAQ APIの構成

構成辞書キーへのマッピングは、以下の通りです。

レガシーSDK Unityプラグインの構成辞書キー	SDK X Unityプラグインの構成辞書キー	注意
Helpshift.HSCUSTOMISSUEFIELDKEY	cifs	-
enableFullPrivacy	fullPrivacy	-
presentFullScreenOniPad	presentFullScreenOniPad	-
enableTypingIndicator	-	「アプリの設定」、「サポートの体験」、「エージェントの入力インジケーターを表示する」トグルの順に移動し、管理者ダッシュボードへと移動します
showConversationResolutionQuestion	-	「アプリの設定」、「解決の体験」、「解決に関する質問」トグルの順に移動し、管理者ダッシュボードへと移動します

その他の構成はすべて非推奨となっており、もうサポートされていません。API構成の詳細については、構成ガイドをご参照ください。

Helpshift User Management API

ユーザーのログイン/ログアウトを管理するために、以下のAPIを置き換えます。

ログイン

レガシーSDKのログインコードを

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
HelpshiftUser user = new HelpshiftUser.Builder ("unique-user-id-746501", "john.doe@app.com")
                                      .setName ("John Doe")
                                      .build ();
_support.login(user);

SDK Xのログインコードで置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.GetInstance();
...
Dictionary<string, string> userDetails = new Dictionary<string, string>
                                          {
                                              { "userId", "unique-user-id-746501" },
                                              { "userEmail", "john.doe@app.com" },
                                              { "userName", "John Doe" }
                                          };
_support.Login(userDetails);

注意

SDK X Unityプラグインへの移行を行う際は、不一致を回避するためにアクティブユーザーを再度ログインさせることをお勧めします。

その他のユーザー管理APIも変更されています。

アクション	レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
ログアウト	logout()	Logout()
匿名ユーザーの消去	clearAnonymousUser()	ClearAnonymousUser()

SDK X Unityプラグインのユーザー管理については、ユーザーガイドをご参照ください。

デザインとテーマ設定

SDKのデザインとテーマ設定は、SDK Xではすべて管理者ダッシュボードへと移動しています。テーマ設定APIのすべての呼び出しと、テーマ設定に関連するすべてのファイルをプロジェクトから削除してください。削除されたAPIは、以下の通りです。-

• setThemes(lightThemeFileName, darkThemeFileName)

• setTheme(themeName)

テーマ設定は、管理者ダッシュボードから構成が可能です。詳細については、SDK Xのテーマ設定ガイドをご参照ください。

文字列のカスタマイズ

文字列のカスタマイズは、まだサポートされておりません。Helpshiftダッシュボードに移行される予定です。SDK Xには反映されなくなるため、プロジェクトで行ったHelpshift SDK関連の文字列カスタマイズはすべて削除してください。

Notification API

APIのシグネチャは変更されています。既存のAPI呼び出しを、以下に説明する新しいものに更新してください。

アクション	レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
デバイストークンを登録する	[HelpshiftCore registerDeviceToken:deviceToken]	[Helpshift registerDeviceToken:deviceToken]
未読メッセージ数をリクエストする	[requestUnreadMessagesCount(isAsync)	RequestUnreadMessageCount(shouldFetchFromServer)

未読メッセージの数を受信するデリゲートメソッドも変更されました。変更前:

using Helpshift;
...
private HelpshiftSdk _support;
this._support = HelpshiftSdk.getInstance();
_support.requestUnreadMessagesCount(true);

// Delegate:
public void didReceiveUnreadMessagesCount(string count) {
    // your code here
}

変更後:

public class HSEventsListener : IHelpshiftEventsListener
{
    ...
    public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
    {
      if(eventName.Equals(HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT))
      {
        if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_COUNT)) {
          Debug.Log("Unread count: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT]);
        }
        if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE)) {
          Debug.Log("Is Unread count from cache: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE]);
        }
      }
    }
}

通知を処理する

通知のクリックを処理するには、レガシーSDKのコードを置き換えます。

- (void) userNotificationCenter:(UNUserNotificationCenter *)center
  willPresentNotification:(UNNotification *)notification
  withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  if([[notification.request.content.userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
    [HelpshiftCore handleNotificationWithUserInfoDictionary:notification.request.content.userInfo
                                                isAppLaunch:false
                                             withController:self.window.rootViewController];
  }
  completionHandler(...);
}

SDK Xのコードで以下のように置き換えます。

- (void) userNotificationCenter:(UNUserNotificationCenter *)center
  willPresentNotification:(UNNotification *)notification
  withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  if([[notification.request.content.userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
    [Helpshift handleNotificationWithUserInfoDictionary:notification.request.content.userInfo
                                                isAppLaunch:false
                                             withController:self.window.rootViewController];
  }
  completionHandler(...);
}

注意

プッシュ通知を使用している場合には、不一致の可能性を回避するためのアプリのアップグレードを終えた後にSDK Xでプッシュトークンの再登録を行うことをお勧めします。

SDK XのNotification APIの詳細については、通知ガイドをご参照ください。SDK Xのデリゲートの詳細については、デリゲートガイドをご参照ください。

インターナショナリゼーション

SDKの言語を設定するAPIは、以下のように変更されています。

レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
setSDKLanguage(locale)	SetSDKLanguage(locale)

注意

不一致の可能性を回避するために、SDK Xでアプリをアップグレードする際にSDKの言語をもう一度設定し直すことをお勧めします。

SDK Xのインターナショナリゼーションの詳細やサポートされている言語のリストについては、インターナショナリゼーションガイドをご参照ください。

トラッキング

以下のAPIをレガシーSDK Unityプラグインから置き換えてください。

メタデータ

レガシーSDKはメタデータAPIを活用して会話にメタデータを付与します（こちらをご参照ください）。メタデータを付与するためのレガシーSDKコードを、同等のSDK Xコードに置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
Dictionary<string, string> customMetadataDictionary = new Dictionary<string, string>();
customMetadataDictionary.Add("Level", "9");
customMetadataDictionary.Add("Spend", "46.55 USD");
customMetadataDictionary.Add("Device Timestamp", DateTime.UtcNow.ToLongTimeString());

Dictionary<string, object> configMap = new Dictionary<string, object>();

configMap.Add("customMetadata", customMetadataDictionary)
_support.ShowFAQs(configMap);

タグ

レガシーSDKはメタデータAPIを活用して会話にタグを付与します。SDK Xはメタデータをサポートしていませんが、タグの付与はサポートしています。タグを付与するために、レガシーSDKコードを置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
Dictionary<string, object> configD = new Dictionary<string, object>();
Dictionary<string, object> configMap = new Dictionary<string, object>();
configMap.Add(HelpshiftSdk.HSTAGSKEY, new string[] {"Whale"});
configD.Add(HelpshiftSdk.HSCUSTOMMETADATAKEY, configMap);
_support.showFAQs(configD);

同等のSDK Xのコードで以下のように置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
Dictionary<string, object> configMap = new Dictionary<string, object>();
configMap.Add("tags", new String[] {"Whale"})
_support.ShowFAQs(configMap);

カスタム問題フィールド

レガシーSDKのコードを以下のように置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
Dictionary<string, object> configD = new Dictionary<string, object>();
Dictionary<string, string[]> customIssueFields = new Dictionary<string, string[]> ();

customIssueFields.Add("join_date", new string[]{ "dt", "1505927361535" });
customIssueFields.Add("level", new String[]{"n", "42"});
customIssueFields.Add("name", new String[]{"sl", "John Doe"});
customIssueFields.Add("address", new String[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
customIssueFields.Add("is_pro", new String[]{"b", "true"});
customIssueFields.Add("currency", new String[]{"dd", "Dollar"});

configD.Add (Helpshift.HSCUSTOMISSUEFIELDKEY, customIssueFields);
_support.showFAQs(configD);

SDK Xのコードで以下のように置き換えます。

private HelpshiftSdk _support = HelpshiftSdk.getInstance();
...
Dictionary<string, object> joiningDate = new Dictionary<string, object>();
joiningDate.Add("type", "date");
joiningDate.Add("value", DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());

Dictionary<string, string> stockLevel = new Dictionary<string, string>();
stockLevel.Add("type", "number");
stockLevel.Add("value", "42");

Dictionary<string, string> employeeName = new Dictionary<string, string>();
employeeName.Add("type", "singleline");
employeeName.Add("value", "John Doe");

Dictionary<string, string> address = new Dictionary<string, string>();
address.Add("type", "multiline");
address.Add("value", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128");

Dictionary<string, string> isPro = new Dictionary<string, string>();
isPro.Add("type", "boolean");
isPro.Add("value", "true");

Dictionary<string, string> currency = new Dictionary<string, string>();
isPro.Add("type", "dropdown");
isPro.Add("value", "Dollar");

Dictionary<string, object> cifDictionary = new Dictionary<string, object>();
cifDictionary.Add("join_date", joiningDate);
cifDictionary.Add("level", stockLevel);
cifDictionary.Add("name", employeeName);
cifDictionary.Add("address", address);
cifDictionary.Add("is_pro", isPro);
cifDictionary.Add("currency", currency);

Map<String, Object> config = new HashMap<>();
config.put("cifs", cifMap);
_support.ShowFAQs(MainActivity.this, config);

注意

"customIssueFields"キーの使用は非推奨になりました。カスタム問題フィールドを渡す方法 として、"cifs"キーの使用を 強く推奨します。

Breadcrumbs

BreadcrumbsのためのAPIは、以下のように変更されています。

アクション	レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
Breadcrumbsを残す	leaveBreadCrumb(breadCrumb)	LeaveBreadcrumb(breadcrumb)
Breadcrumbsを消去する	clearBreadCrumbs()	ClearBreadcrumbs()

デバッグログ

デバッグログを追加するためのAPIのシグネチャは変更されていません。ログの追加には、SDK X UnityプラグインのHelpshiftLogと同じ名前のクラスを用意しています。ログの追加には、そのメソッドを利用することができます。 詳細については、トラッキングガイドをご参照ください。

Helpshiftのデリゲート

Helpshiftのデリゲートを登録するためのAPIは、以下のように変更されています。

レガシーSDK UnityプラグインのAPI	SDK X UnityプラグインのAPI
registerDelegates()	SetHelpshiftEventsListener(eventsListener)

レガシーSDK Unityプラグインでは、SDKの各イベントは個別のメソッドを持っていました。SDK X Unityプラグインでは、すべてのイベントはデリゲートのHandleHelpshiftEvent(eventName,eventData)メソッドで受信されます。イベントの一覧については、こちらのガイドをご参照ください。

SDK X UnityプラグインでサポートされていないレガシーSDK Unityプラグインのメソッドの中で、対応するイベントがないものは以下の通りです。

• userClickOnAction(serializedJSONUserActionData)

• displayAttachmentFile(path)

• didCheckIfConversationActive(isActive)

レビューとフィードバック

エージェントによるアプリのレビューは、SDK Xではサポートされています。この機能の詳細については、こちらをご参照ください

以下の機能は、SDK Xで非推奨となりました。

• 手動のアプリ評価リクエスト
• 自動のレビューリクエスト

ディープリンク

ディープリンクは、レガシーSDKと同様にSDK Xでもサポートされています。詳細については、ディープリンクをご参照ください。

トラブルシューティング

SDK X Unityプラグインへのアップグレード後のコンパイルエラー

• サポートされているAPIおよび構成については、このガイドに記載されているように、すべてのレガシーSDK Unityプラグインのコードが対応するSDK X Unityプラグインのコードに置き換えられていることをご確認ください。

• サポートされていないAPIおよび構成については、このガイドに記載されているように、すべてのレガシーSDK Unityプラグインのコードが削除されていることをご確認ください。

お問い合わせ

レガシーSDK UnityプラグインからSDK X Unityプラグインへの移行に関して問題が発生した場合には、support@helpshift.comまでお問い合わせください。