移行ガイド

SDK XはハイブリッドSDKであり、ダウンタイムがなく、またアプリのアップデートを行うことなくアップデートの大半を無線を介してエンドユーザーへと送信することができるため、イノベーションを素早く展開することができます。

この移行ガイドでは、HelpshiftのレガシーSDKからSDK Xへの移行を行うために必要となる手順について説明します。

SDK Xへの移行を行うための手順

レガシーSDKからSDK Xへの移行

#1

移行の対応状況を確認する

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

#2

SDK Xにアップデートする

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

#3

移行のテストを行う

機能の検証を行う

非対応の機能

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

• ガイド付きの問題提出。
• 埋め込み可能なサポートフラグメント。
• 問題に関する記述の長さの最小値設定。
• SDKのUI文字列のカスタマイズ。
• レビューリクエストの自動化。
• ライトテーマとダークテーマの切り替え。

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

対応するSDKのバージョン

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

注意

6.xより前のバージョンのSDKからの移行

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

SDKのGradleインポートをSDK Xライブラリへと移行する

Helpshift SDKについてのGradleのimport文を、以下のように変更します。

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.helpshift:helpshift-sdkx:10.1.0'
}

もしもHelpshift SDKのためだけにDesign、RecyclerView、CardViewの依存関係を追加した場合、SDK Xではこれらのライブラリは使用されないため、削除することができます。

注意

レガシーSDKの依存関係はアプリから削除してください。両方の依存関係を保持することはできません。

Gradle以外の統合ソースは、サポート対象外となりました。

例:

IntelliJ/Eclipseベースのプロジェクト

Mavenベースのプロジェクト

"install"の呼び出しをアップデートする

installの呼び出しを、以下のようにアップデートします。

try {
    Helpshift.install(this,
                  "<App Id from the Helpshift Dashboard>",
                  "<Domain name from the Helpshift Dashboard>",
                  config);
} catch (UnsupportedOSVersionException e) {
    // Android OS versions prior to Lollipop (< SDK 21) are not supported.
}

詳細については、「SDK X・はじめに」ガイドをご参照ください。

"install"の呼び出しの構成

SDK Xのinstall APIは初期化のための構成としてMapを取り込みます。InstallConfigクラスは削除され、Mapによって置き換えられる必要があります。

InstallConfigからMapのキーに対する以下のような関数のマッピングに基づき、installの呼び出しで渡された構成を更新します。

レガシーSDKのInstallConfig	SDK X: Mapのキー	値の例
InstallConfig.Builder.setNotificationIcon	"notificationIcon"	R.drawable.notification_icon
InstallConfig.Builder.setLargeNotificationIcon	"notificationLargeIcon"	R.drawable.notification_large_icon
InstallConfig.Builder.setEnableInAppNotifications	"enableInAppNotification"	true/false
InstallConfig.Builder.setNotificationSound	"notificationSoundId"	R.raw.notification_sound
InstallConfig.Builder.setSupportNotificationChannelId	"notificationChannelId"	"ABC App Channel"
InstallConfig.Builder.setEnableDefaultFallbackLanguage	この構成は削除されました
InstallConfig.Builder.setFont	この構成は削除されました
InstallConfig.Builder.setScreenOrientation	"screenOrientation"	ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
InstallConfig.Builder.setEnableLogging	"enableLogging"	true/false
InstallConfig.Builder.disableErrorReporting	この構成は削除されました

注意

非推奨となった構成はすべて削除されており、サポート対象外となりました。

構成に関する詳細については、こちらのドキュメントをご参照ください — SDKの構成 - Android向けのHelpshift SDK X

会話とFAQのAPI

会話とFAQ向けのパブリックAPIを、以下のようにアップデートします。

レガシーSDK	SDK X
Support.showConversation(MyActivity.this); Support.showConversation(MyActivity.this, apiConfig);	Helpshift.showConversation(MyActivity.this, config);
Support.showFAQs(MyActivity.this); Support.showFAQs(MyActivity.this, apiConfig);	Helpshift.showFAQs(MyActivity.this, config);
Support.showFAQSection(MyActivity.this, "11"); Support.showFAQSection(MyActivity.this, "11", apiConfig);	Helpshift.showFAQSection(MyActivity.this, "11", config);
Support.showSingleFAQ(MyActivity.this, "51"); Support.showSingleFAQ(MyActivity.this, "51", apiConfig);	Helpshift.showSingleFAQ(MyActivity.this, "51", config);
タグによるFAQのフィルタリング	現在対応していません
ガイド付きの問題提出	現在対応していません
埋め込み可能なフラグメント	現在対応していません

SDK XのパブリックAPIに関する詳細については、こちらのドキュメントをご参照ください — HelpshiftのAPI - Android向けのHelpshift SDK X。

会話とFAQのAPIの構成

会話およびFAQのAPIで渡される構成を、以下のようにアップデートします。

レガシーSDKのApiConfig	SDK X: Mapのキー
ApiConfig.Builder.setEnableFullPrivacy	"fullPrivacy"
ApiConfig.Builder.setCustomIssueFields	"cifs"
ApiConfig.Builder.setShowConversationResolutionQuestion	Helpshiftの管理者ダッシュボードに移動します。 「アプリの設定」、「解決の体験」、「解決に関する質問」トグルの順に移動します
ApiConfig.Builder.setEnableTypingIndicator	Helpshiftの管理者ダッシュボードに移動します。 「アプリの設定」、「サポート体験」、「エージェントの入力インジケーターを表示する」トグルの順に移動します
ApiConfigのその他の構成は削除されました	現在その他の構成には対応していません

非推奨となった以下の構成は、SDKから削除されました。

• gotoConversationAfterContactUs
• requireEmail
• hideNameAndEmail
• enableTypingIndicator
• showConversationResolutionQuestion

ユーザー管理

ログイン

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

HelpshiftUser user = new HelpshiftUser.Builder("unique-user-id-746501", "john.doe@app.co")
                                              .setName("John Doe")
                                              .setAuthToken("generated-user-authentication-token")
                                              .build();

Core.login(user);

SDK X login:

Map<String, Object> userData = new HashMap<>();
userData.put("userId", "unique-user-id-746501");
userData.put("userEmail", ""john.doe@app.co");
userData.put("userName", "John Doe");
userData.put("userAuthToken", "generated-user-authentication-token");

Helpshift.login(userData);

ログアウト

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

Core.logout()

SDK X logout:

Helpshift.logout()

匿名ユーザーの消去

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

Core.clearAnonymousUser();

SDK X API:

Helpshift.clearAnonymousUserOnLogin();

ユーザー認証失敗リスナー

SDK Xで認証失敗リスナーのデリゲートをHelpshiftEventListenerに置き換えます。

レガシーSDKのデリゲートを削除します。

import com.helpshift.support.Support.Delegate
...
...

class MyDelegate implements Delegate {
    .
    .
    .
    .

    @Override
    void authenticationFailed(HelpshiftUser user, AuthenticationFailureReason reason) {
        // your code here
    }
}

...
...

Support.setDelegate(new MyDelegate());

認証失敗のアップデートには、SDK XのHelpshiftEventListenerを使用します。

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
     // ....
  }

  @Override
  public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
    Log.e(TAG, reason);
    // Your code here
  }
});

ユーザー管理に関する詳細については、こちらのドキュメントをご参照ください — ユーザー - Android向けのHelpshift SDK X

注意

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

デザインとカスタマイズのサポート

SDK Xのデザインとカスタマイズは、Helpshiftダッシュボードへと完全に移行されました。

Helpshift SDKのデザイン、テーマ設定、カスタマイズに関連するコードは、すべて削除してください。これらの代わりに、Helpshiftダッシュボードで設定を行ってください。

デザインとカスタマイズに関する詳細については、こちらのドキュメントをご参照ください — デザイン - Android向けのHelpshift SDK X

注意

テーマ設定とカスタマイズは、SDK Xでは未対応です。2022年のロードマップに追加される予定です。

文字列のカスタマイズ

文字列のカスタマイズは未対応です。Helpshiftダッシュボードに移行される予定です。

SDK Xには反映されなくなるため、アプリで行ったHelpshift SDK関連の文字列カスタマイズはすべて削除してください。

通知

通知を処理するために、以下のAPIをレガシーSDKからSDK X APIへと置き換えてください。

レガシーSDK	SDK X
Core.registerDeviceToken(context, pushToken);	Helpshift.registerPushToken(pushToken);
Core.handlePush(context, intent);	Helpshift.handlePush(data);
通知の数を同期的に取得します。 Support.getNotificationCount()	対応していません
通知の数を非同期的に取得します。 Support.getNotificationCount(countHandler, failHandler);	Helpshift.requestUnreadMessageCount(shouldFetchFromServer)

非同期のrequestUnreadMessageCountの結果は、HelpshiftEventListenerのイベントとして提供されます。

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT:
        int count = (int) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT);
        boolean fromCache = (boolean) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE);
        if (fromCache) {
          Log.d("Notification Count", "local" + count);
        } else {
          Log.d("Notification Count", "server" + count);
        }
    }
  }

注意

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

通知の処理に関する詳細については、こちらのドキュメントをご参照ください — 通知 - Android向けのHelpshift SDK X

SDKの言語

レガシーSDK	SDK X
Core.setSDKLanguage("fr");	Helpshift.setLanguage("fr");`

注意

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

インターナショナリゼーションに関する詳細については、こちらのドキュメントをご参照ください — インターナショナリゼーションを行う - Android向けのHelpshift SDK X

トラッキング

BreadCrumb

レガシーSDK API Support.leaveBreadCrumb("Went to Preferences Screen");をSDK X API Helpshift.leaveBreadCrumb("Went to Preferences Screen")に置き換えます

レガシーSDK API Support.clearBreadCrumbs();をSDK X API Helpshift.clearBreadCrumbs()に置き換えます

デバッグログ

デバッグログのレガシーSDKサポートは、SDK Xではこちらに記載されているデバッグログに置き換えられました

アクティブな会話のチェック

レガシーSDK API Support.isConversationActive()はSDK Xでは対応していません

会話へのメタデータの追加

MetaDataクラスは削除されました。

メタデータの代わりに、CIFを使用することをお勧めしています。詳細については、こちらの記事をご覧ください

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

HashMap<String, String> customMetadata = new HashMap<String, String();
customMetadata.put("usertype","paid");
customMetadata.put("level","7");
customMetadata.put("score","12345");

HashMap<String, Object> config = new HashMap<>();
config.put("customMetadata", customMetadata);

Helpshift.showConversation(MainActivity.this, config);

会話へのタグの追加

tagsを渡す場合、レガシーSDKコードでは以下のように記述します。

String[] tags = new String[]{"foo", "bar"};

HashMap<String, Object> userData = new HashMap<>();
Metadata metadata = new Metadata(userData, tags);

private void showHelp () {
  ApiConfig apiConfig = new ApiConfig.Builder()
                         .setCustomMetadata(metadata)
                         .build();
  Support.showFAQs(MainActivity.this, apiConfig);

以下のSDK X APIを使用します。

Map<String, Object> config = new HashMap<>();
    config.put("tags", new String[]{"foo", "bar"});

    Helpshift.showConversation(MainActivity.this, config);

CIFのサポート

レガシーSDKで以下のようにCIFが設定されている場合には、

Map<String, String[]> cifs = new HashMap<>();
cifs.put("join_date", new String[]{"dt", "1505927361535"});
cifs.put("level", new String[]{"n", "42"});
cifs.put("name", new String[]{"sl", "John Doe"});
cifs.put("address", new String[]{"ml", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128"});
cifs.put("is_pro", new String[]{"b", "true"});
cifs.put("currency", new String[]{"dd", "Dollar"});

...
...

private void showHelp() {
         ApiConfig apiConfig = new ApiConfig.Builder()
                                            .setCustomIssueFields(cifs)
                                            .build();
        Support.showFAQs(MainActivity.this, apiConfig);

以下のSDK X APIを使用して上記の例のようなCIFを設定します。

Map<String, String> joiningDate = new HashMap<>();
    joiningDate.put("type", "date");
    joiningDate.put("value", "1505927361535");

    Map<String, String> stockLevel = new HashMap<>();
    stockLevel.put("type", "number");
    stockLevel.put("value", "42");

    Map<String, String> employeeName= new HashMap<>();
    employeeName.put("type", "singleline");
    employeeName.put("value", "John Doe");

    Map<String, String> isPro = new HashMap<>();
    isPro.put("type", "boolean");
    isPro.put("value", "true");

    Map<String, String> address = new HashMap<>();
    address.put("type", "multiline");
    address.put("value", "3346, Sunny Glen Lane, Warrensville Heights, Ohio - 44128");

    Map<String, String> currency = new HashMap<>();
    currency.put("type", "dropdown");
    currency.put("value", "Dollar");

    Map<String, Object> cifMap = new HashMap<>();
    cifMap.put("join_date", joiningDate);
    cifMap.put("level", stockLevel);
    cifMap.put("name", employeeName);
    cifMap.put("is_pro", isPro);
    cifMap.put("address", address)
    cifMap.put("currency", currency)


    Map<String, Object> config = new HashMap<>();
    // other configs...
    //..
    config.put("cifs", cifMap);

    Helpshift.showFAQs(MainActivity.this, config);

Note

The "customIssueFields" key has been deprecated. We strongly recommend transitioning to using the "cifs" key as the preferred method for passing custom issue fields.

詳細については、こちらのドキュメントをご参照ください — CIF - Android向けのHelpshift SDK X

Helpshiftのデリゲート

レガシーSDKのDelegateクラスで報告されたイベントは、SDK XのHelpshiftEventListenerコールバックインターフェースで報告されるようになりました。 すべてのイベントは、このリスナークラスのonEventOccurredメソッドで期待される値の定義された定数とともに報告されるようになりました。古いDelegateクラスのこれらのイベントに基づいてコードを更新する必要があります。

対象のイベント詳細については、こちらのドキュメントをご参照ください — Helpshiftのデリゲート - Android向けのHelpshift SDK X

レガシーSDKでは、以下のイベントはサポートされなくなりました。

• userClickOnAction

• displayAttachmentFile

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

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

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

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

ディープリンク

ディープリンクは、レガシーSDKと同様にSDK Xでも対応しています — ディープリンク - Android向けのHelpshift SDK X

トラブルシューティング

Helpshift SDKに起因するコンパイルエラー

レガシーSDKに関連するすべてのコードが削除されていることをご確認ください。

こちらに記載されているように、Gradle依存関係が正しく追加されていることをご確認ください。

使用している新しい/置き換えられたAPIが正しいパラメーターを持っていることをご確認ください。

プッシュ通知が正しく機能しない

SDK Xでプッシュトークンを登録するために使用する新しいAPIに移行していることをご確認ください。

プッシュ通知を処理する新しいAPI（Core.handlePush()の代わりに導入されたHelpshift.handlePush()）が使用されるように正しく移行が完了していることをご確認ください

SDKからイベントの更新を取得しない

リスナーHelpshift.setHelpshiftEventListener()を正しく登録し、イベント処理コードをSupport.setDelegate()から移行していることをご確認ください

お問い合わせ

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