移行ガイド

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.x以上のレガシーSDKからSDK Xへの移行をサポートしています。

注意

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

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

Helpshiftの依存関係を更新する

レガシーSDKとSDK XのXcodeおよびiOSのバージョン要件は、変更されていません。

CocoaPodsを使った自動統合

• Podfileから既存のHelpshiftの依存関係を削除する
• Helpshift SDK Xをプロジェクトに追加するには、こちらの手順に従ってください

手動での統合

• プロジェクトからHelpshiftに関連するファイルをすべて削除します。関連するファイルには、以下のものがあります。
  • 使用するHelpshift SDKのバージョンに応じたHelpshift.xcframeworkまたはHelpshift.framework
  • HelpshiftCustomLocalizations/フォルダー
  • HelpshiftCustomThemes/フォルダー
• Helpshift SDK Xをプロジェクトに追加するには、こちらの手順に従ってください

コードの変更

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

インポート文

• Helpshiftモジュールは、HelpshiftではなくHelpshiftXと呼ばれています。 Helpshift APIを使用する予定のすべてのファイルで、@import Helpshift;を@import HelpshiftX;で置き換えてください。
• プロジェクトのヘッダーファイルで#import <Helpshift/HelpshiftCore.h>のようなインポート文を使用している場合には、モジュールのインポート文に置き換える必要があります。

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

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

@import HelpshiftX;
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    NSDictionary *config = @{} // Your config
    [Helpshift installWithPlatformId:@"YOUR_PLATFORM_ID"
                              domain:@"YOUR_DOMAIN"
                              config:config];
    ...
    return YES;
}

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

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

SDK Xのインストール呼び出しは、HelpshiftInstallConfigオブジェクトではなく辞書を持っています。インストール構成プロパティの辞書キーへのマッピングは、以下の通りです。

レガシーSDKのInstallConfigプロパティ	SDK Xのインストール辞書キー
enableLogging	enableLogging
enableInAppNotifications	enableInAppNotification

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

HelpshiftのConversation APIとFAQ API

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

レガシーSDKのAPI	SDK X API
showConversation:withOptions:	showConversationWith:config:
showFAQs:withOptions:	showFAQsWith:config:
showFAQSection:withController:withOptions:	showFAQSection:with:config:
showSingleFAQ:withController:withOptions:	showSingleFAQ:with:config:
タグによるFAQのフィルタリング	現在対応していません
ガイド付きの問題提出	現在対応していません
埋め込みのメッセージングエクスペリエンス	現在対応していません

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

Conversation APIとFAQ APIの構成

SDK XのConversation APIとFAQ APIは、HelpshiftAPIConfigオブジェクトではなく辞書パラメーターを持っています。API構成プロパティの辞書キーへのマッピングは、以下の通りです。

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

その他の構成はすべて非推奨で、サポート対象外です。API構成の詳細については、SDKの構成ガイドをご参照ください。

Helpshift User Management API

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

ログイン

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

HelpshiftUserBuilder *userBuilder = [[HelpshiftUserBuilder alloc] initWithIdentifier:@"unique-user-id-746501"
          andEmail:@"john.doe@app.co"];
userBuilder.name = @"John Doe";
userBuilder.authToken = @"generated-user-authentication-token";
HelpshiftUser *user = userBuilder.build;
[HelpshiftCore login:user];

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

NSDictionary *userDetails = @{ HelpshiftUserName:@"John Doe",
                              HelpshiftUserEmail:@"john.doe@app.co",
                         HelpshiftUserIdentifier:@"unique-user-id-746501",
                          HelpshiftUserAuthToken:@"generated-user-authentication-token" };

[Helpshift loginUser:userDetails];

注意

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

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

アクション	レガシーSDKのAPI	SDK X API
ログアウト	[HelpshiftCore logout];	[Helpshift logout];
匿名ユーザーの消去	[HelpshiftCore clearAnonymousUser];	[Helpshift clearAnonymousUserOnLogin];

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

デザインとテーマ設定

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

• setTheme:
• setLightTheme:darkTheme:

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

文字列のカスタマイズ

文字列のカスタマイズは未対応です。Helpshiftダッシュボードに移行される予定です。SDK Xには反映されなくなるため、アプリで行ったHelpshift SDK関連の文字列カスタマイズはすべて削除してください。

Notification API

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

アクション	レガシーSDKのAPI	SDK X API
デバイストークンを登録する	[HelpshiftCore registerDeviceToken:deviceToken];	[Helpshift registerDeviceToken:deviceToken];
アプリ内通知を一時停止する	[HelpshiftSupport pauseDisplayOfInAppNotification:YES];	[Helpshift pauseDisplayOfInAppNotification:YES];
未読メッセージ数をリクエストする	[HelpshiftSupport requestUnreadMessagesCount:YES];	[Helpshift requestUnreadMessageCount:YES];

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

- (void) didReceiveUnreadMessagesCount:(NSInteger)count {
    dispatch_async(dispatch_get_main_queue(), ^{
        [yourView setTextLabel:[NSString stringWithFormat:@"%d",count];
    });
}

変更後:

- (void) handleHelpshiftEvent:(NSString *)eventName withData:(NSDictionary *)data {
    ...
    if([eventName isEqualToString:HelpshiftEventNameReceivedUnreadMessageCount]) {
        int count = data[HelpshiftEventDataUnreadMessageCount];
        dispatch_async(dispatch_get_main_queue(), ^{
            [yourView setTextLabel:[NSString stringWithFormat:@"%d",count];
        });
    }
}

通知を処理する

通知のクリックを処理するには、レガシー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のAPI	SDK X API
[HelpshiftCore setLanguage:@"fr"];	[Helpshift setLanguage:"fr"];

注意

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

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

トラッキング

以下のAPIをレガシーSDKから置き換えてください。

メタデータ

メタデータの代わりに、CIFの使用を推奨しております。

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

NSDictionary *customMetadata = @{ @"usertype": @"paid",
                                  @"level": @"7",
                                  @"score": @"12345"
 };

NSDictionary *config = @{ @"customMetadata" : customMetadata };
[Helpshift showConversationWith:self config:config];

タグ

レガシーSDKはメタデータAPIを活用して会話にタグを付与します。タグを付与するために、レガシーSDKコードを置き換えます。

HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customMetaData = [[HelpshiftSupportMetaData alloc] initWithMetaData:@{ /* ... */ }
                                                                    andTags:@[@"feedback",@"paid user",@"v4.1"]];
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfig:apiConfig]

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

NSArray *tags = @[@"feedback",@"paid user",@"v4.1"];
NSDictionary *config = @{@"tags":tags};
[Helpshift showConversationWith:self config:config];

カスタム問題フィールド

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

NSMutableDictionary *customIssueFieldsDict = [NSMutableDictionary dictionary];
customIssueFieldsDict[@"name"] = @[@"sl",@"John Doe"];
customIssueFieldsDict[@"address"] = @[@"ml",@"This is user's long bio"];
customIssueFieldsDict[@"level"] = @[@"n",@"42"];
customIssueFieldsDict[@"is_pro"] = @[@"b",@"true"];
customIssueFieldsDict[@"currency"] = @[@"dd", @"Dollar"];
customIssueFieldsDict[@"join_date"] = @[@"dt", @"1505927361535"];

HelpshiftAPIConfigBuilder *builder = [[HelpshiftAPIConfigBuilder alloc] init];
builder.customIssueFields = customIssueFieldsDict;
HelpshiftAPIConfig *apiConfig = [builder build];
[HelpshiftSupport showFAQs:self withConfig:apiConfig];

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

NSDictionary *cifs = @{ @"name": @{ @"type":@"singleline", @"value":@"John Doe" },
                     @"address": @{ @"type":@"multiline", @"value":@"This is user's long bio" },
                       @"level": @{ @"type":@"number", @"value":@"42" },
                      @"is_pro": @{ @"type":@"boolean", @"value":@"true" },
                    @"currency": @{ @"type":@"dropdown", @"value":@"Dollar" },
                   @"join_date": @{ @"type":@"date", @"value":@"1505927361535" } };

NSDictionary *config = @{ @"cifs" : cifs };
[Helpshift showConversationWith:self config: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.

Breadcrumbsとデバッグログ

アクション	レガシーSDKのAPI	SDK X API
Breadcrumbsを残す	[HelpshiftSupport leaveBreadCrumb:@"Custom String"];	[Helpshift leaveBreadcrumb:@"Custom String"];
Breadcrumbsを消去する	[HelpshiftSupport clearBreadCrumbs];	[Helpshift clearBreadcrumbs];
デバッグログを追加する	[HelpshiftSupport addLog:message];	[Helpshift addLog:message];

SDK XのトラッキングAPIについては、トラッキングガイドをご参照ください。

Helpshiftのデリゲート

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

レガシーSDKのAPI	SDK X API
[[HelpshiftSupport sharedInstance] setDelegate:delegate];	[[Helpshift sharedInstance] setDelegate:delegate];

レガシーSDKでは、SDKの各イベントは個別のメソッドを持っていました。SDK Xでは、すべてのイベントはデリゲートのhandleHelpshiftEvent:withData:メソッドで受信されます。イベントの一覧については、こちらのガイドをご参照ください。

SDK Xで対応外のレガシーSDKメソッドの中で、関連するイベントがないものは以下の通りです。

• userDidClickOnActionWithType:withData:
• displayAttachmentFileAtLocation:onViewController:
• didCheckIfConversationActive

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

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

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

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

ディープリンク

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

トラブルシューティング

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

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

お問い合わせ

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