レガシーiOS SDK

ノート

ここでは、デジタル・アシスタントのバージョン19.4.1以下でのみ動作するレガシーiOS SDKについて説明します。より新しいバージョンのデジタル・アシスタントの場合、Oracle Native iOS SDKを使用してください。

クライアントSDKを使用すると、デジタル・アシスタントをiOSアプリケーションと統合できます。スキルはiOSと直接は通信しません。かわりに、チャット・サーバーが仲介役となって、HTTPSリクエストを介してスキルと通信し、WebSocketを介してiOSと通信します。SDKのクライアント・ライブラリをネイティブ・アプリケーションにデプロイすると、適切なメッセージ・ハンドラへのWebSocket接続が確立されます。

client_sdks-ios.pngの説明が続きます

このような統合では、デジタル・アシスタントでiOSチャネルを作成し、生成されたアプリケーションIDをクライアント・アプリケーション・コードにコピーします。

フレームワークのインストール

開発およびテスト用の場合は、フレームワーク(Bots.frameworkディレクトリのSDK ZIPにある)をアプリケーション・プロジェクトに手動でインストールできますが、本番環境用の場合は、Cocoapodsを通じてローカルに配布する必要があります。

開発およびテスト用のフレームワークのインストール

この方法は、フレームワークのテストに使用します。フレームワークを手動でプロジェクトに追加した場合、アプリケーション・ストアにアプリケーションを発行することはできません。

フレームワークを手動でプロジェクトに追加するには:

  1. Oracle Technology NetworkのODAおよびOMCのダウンロード・ページからデジタル・アシスタントのClient SDK for iOSモジュールをダウンロードして、ローカル・マシンに解凍します。

  2. 「File」→「Add Files to My_Project」を選択し、ファイル・ピッカーでBots.frameworkを選択して、フレームワークをXcodeプロジェクトに追加します。

  3. プロジェクト設定で、アプリケーション・ターゲットの「General」タブにある「Embedded Binaries」のリストにBots.frameworkを追加します。

    これで、フレームワーク(#import <Bots/Bots.h>)をインポートし、コードで使用できるようになりました。

本番環境用のフレームワークのインストール

本番環境用にアプリケーションを準備できたら、CocoaPodsを使用してBots.frameworkおよび関連するAPIリファレンス・ドキュメントを配布します。Podspecを配布パッケージの一部としてローカルに公開します。

ローカルのPodspecを使用したフレームワークの配布

ローカルのPodspecを使用してフレームワークを配布できます。ユーザーは、このファイルをダウンロードした後、CocoaPadsコマンド行ツールを使用してインストールします。

ローカルのPodspecを公開するには:

  1. 次の属性を定義するPodspecファイルを作成します:
    • version
    • summary
    • homepage
    • license
    • author
  2. フレームワーク自体を含むZIPファイルを作成します。
  3. ビルド・プロセスに使用可能なサーバー上でZIPファイルをホストします。

アプリケーションでのクライアントSDKの初期化

コードでSDKを起動する前に、iOSチャネルの追加時にボット用に生成されるアプリケーションIDを使用してライブラリを初期化する必要があります。このIDを取得するには、「チャネルの追加」をクリックして「チャネルの作成」ダイアログを開きます。iOSチャネルの名前を追加し、チャネル・タイプとして「iOS」を選択します。「作成」をクリックした後、デジタル・アシスタントによってアプリケーションIDが生成されます。次に、このIDを使用して、applicationDidFinishLaunchingWithOptions:メソッドのYOUR APP IDを置き換えます:
  • Objective-C

    [Bots initWithSettings:[OMCSettings settingsWithAppId:@"YOUR_APP_ID"] completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
        // Your code after init is complete
    }];
  • Swift:
    Bots.initWith(OMCSettings(appId: "YOUR_APP_ID")) { (error: Error?, userInfo: [AnyHashable : Any]?) in// Your code after init is complete}
次の行を追加すると、ロード終了後にアプリケーション内の任意の場所にデジタル・アシスタントUIを表示できます:
  • Objective-C:
    [Bots show];
  • Swift:
    Bots.show();

その他の関数のコール

SDKが正常に初期化されたら、その他の関数をコールできます。たとえば、ユーザーの名、姓および電子メール・アドレスを更新できます:
// Update first name and last name
   [Bots setUserFirstName:@"John"
           lastName:@"Smith"];

// Update email address
   [OMCUser currentUser].email = @"john.smith@example.com";

SDKの更新

次のコマンドを実行して、Carthageの依存関係を更新します:
$ carthage update

アプリケーションのinfo.plistへの必須キーの追加

Client SDK for iOSでは、特定の機能を使用するためのユーザー権限を要求する必要がある場合があります。機能によっては、アプリケーションのInfo.plistに説明を入力して、アクセスが必要な理由を説明する必要があります。これらの説明は、ユーザーに権限を要求するときに表示されます。

イメージ

Client SDK for iOSを使用すると、ユーザーはイメージを送信できます。この機能をサポートするには、次のキーに関する説明を入力する必要があります:
  • NSCameraUsageDescription—アプリケーションがカメラにアクセスする理由を説明します(例: ${PRODUCT_NAME}にイメージを送信するためにカメラ権限が必要です)。詳細は、NSCameraUsageDescriptionに関するiOSのドキュメントを参照してください。

  • NSPhotoLibraryUsageDescription—アプリケーションが写真ライブラリにアクセスする理由を説明します(例: ${PRODUCT_NAME}にイメージを送信するために写真ライブラリ権限が必要です)。詳細は、NSPhotoLibraryUsageDescriptionに関するiOSのドキュメントを参照してください。

ノート

iOS 10以降、これらの値は必須です。アプリケーションのInfo.plistにこれらが存在しない場合、イメージを送信するオプションは表示されません。

ロケーション

Client SDK for iOSを使用すると、ユーザーは現在ロケーションを送信することもできます。この機能をサポートするには、アプリケーションでのロケーション・サービスの使用に応じて、次のいずれかのキーに関する説明を入力する必要があります。SDKは、指定されたキーに応じてユーザーにロケーションを要求します:
  • NSLocationWhenInUseUsageDescription—アプリケーションの使用中にそのアプリケーションがユーザーのロケーション情報にアクセスする理由について説明します(例: ${PRODUCT_NAME}に現在ロケーションを送信するためにロケーション情報サービスが必要です)。この権限は、アプリケーションでロケーション・サービスを使用していない場合に推奨されます。両方のキーが含まれている場合、SDKはこちらにデフォルト設定されます。NSLocationWhenInUseUsageDescriptionに関するiOSのドキュメントを参照してください。

  • NSLocationAlwaysUsageDescription—アプリケーションがユーザーのロケーション情報に常時アクセスする理由について説明します(例: ${PRODUCT_NAME}に現在ロケーションを送信するためにロケーション情報サービスが必要です)。NSLocationAlwaysUsageDescriptionに関するiOSのドキュメントを参照してください。

ノート

これらのキーのいずれも指定しなかった場合、ユーザーが現在ロケーションを送信しようとすると失敗します。

Botsヘッダー・ファイルのインポート

Botsファイルをアプリケーションのデリゲートの.mファイルおよびこのファイルを使用する他の場所にインポートします。

  • Objective-C:
    #import <Bots/Bots.h>
  • Swift:
    import Bots

iOSアプリケーションのローカリゼーション

ボットに表示される文字列はすべて、カスタマイズおよびローカライズできます。デジタル・アシスタントではいくつかの言語をデフォルトで使用できますが、新しい言語を簡単に追加することもできます。文字列をローカライズする場合、デジタル・アシスタントは最初にアプリケーションのバンドル、次にデジタル・アシスタントのバンドルでBotsLocalizable.stringsを探すため、文字列のカスタマイズおよび他の言語のサポートの追加が可能になります。

ローカリゼーションの有効化

デジタル・アシスタントで英語以外の言語を表示するには、最初にアプリケーションでその言語のサポートを有効にする必要があります。Xcodeプロジェクト設定で2番目の言語を有効にできます:
xcode_project_language_settings.pngの説明が続きます

このようにすると、サポートされている言語のデバイス言語でデジタル・アシスタントが表示されます。

次の言語がデジタル・アシスタントのClient SDK for iOSに付属しています: アラビア語、英語、フィンランド語、フランス語、ドイツ語、イタリア語、日本語、韓国語、中国語(繁体字および簡体字)、ペルシア語、ポルトガル語(ブラジルおよびポルトガル)、ロシア語、スロベニア語、スペイン語およびスウェーデン語。
ノート

ローカリゼーションはキャッシュの対象です。変更内容が表示されない場合は、プロジェクトのクリーニング、シミュレータのリセット、テスト・デバイスからのアプリケーションの削除を実行することをお薦めします。

文字列のカスタマイズ

デジタル・アシスタントを使用すると、Appleのローカリゼーション・メカニズムを介して表示される文字列をカスタマイズできます。1つ以上の文字列をオーバーライドするには、Xcodeプロジェクトに空の文字列ファイルBotsLocalizable.stringsを追加し、オーバーライドするキーに新しい値を指定します。たとえば、"Messages"ヘッダーと"Done"ボタンを変更する場合、次の内容を含むファイルを作成します:
"Messages" = "My Messages"

"Done" = "I'm Done"
言語全体で文字列のカスタマイズを有効にするには、XcodeでBotsLocalizable.stringsファイルをローカライズします。
ios_localize.pngの説明が続きます

BotsLocalizable.stringsファイル

キーの完全なセットを次に示します:
/* Nav bar button, action sheet cancel button */
"Cancel" = "...";

/* Conversation title */
"Messages" = "...";

/* Conversation header. Uses CFBundleDisplayName */
"This is the start of your conversation with the %@ team. We'll stay in touch to help you get the most out of your app.\nFeel free to leave us a message about anything that’s on your mind. We’ll get back to your questions, suggestions or anything else as soon as we can." = "...";

/* Conversation header when there are previous messages */
"Show more..." = "...";

/* Conversation header when fetching previous messages */
"Retrieving history..." = "...";

/* Error message shown in conversation view */
"No Internet connection" = "...";

/* Error message shown in conversation view */
"Could not connect to server" = "...";

/* Error message shown in conversation view */
"An error occurred while processing your action. Please try again." = "...";

/* Error message shown in conversation view */
"Reconnecting..." = "...";

/* Fallback used by the in app notification when no message author name is found */
"%@ Team" = "...";

/* Conversation send button */
"Send" = "...";

/* Conversation text input place holder */
"Type a message..." = "...";

/* Conversation nav bar left button */
"Done" = "...";

/* Failure text for chat messages that fail to upload */
"Message not delivered. Tap to retry." = "...";

/* Status text for chat messages */
"Sending..." = "...";

/* Status text for sent chat messages */
"Delivered" = "...";

/* Status text for chat messages seen by the appMaker */
"Seen" = "...";

/* Timestamp text for recent messages */
"Just now" = "...";

/* Timestamp text for messages in the last hour */
"%.0fm ago" = "...";

/* Timestamp text for messages in the last day */
"%.0fh ago" = "...";

/* Timestamp text for messages in the last week */
"%.0fd ago" = "...";

/* Action sheet button label */
"Take Photo" = "...";

/* Action sheet button label */
"Use Last Photo Taken" = "...";

/* Action sheet button label */
"Choose from Library" = "...";

/* Photo confirmation alert title */
"Confirm Photo" = "...";

/* Action sheet button label */
"Resend" = "...";

/* Action sheet button label */
"View Image" = "...";

/* Error displayed in message bubble if image failed to download */
"Tap to reload image" = "...";

/* Error displayed as message if location sending fails */
"Could not send location" = "...";

/* Error title when user selects "use latest photo", but no photos exist */
"No Photos Found" = "...";

/* Error description when user selects "use latest photo", but no photos exist */
"Your photo library seems to be empty." = "...";

/* Error title when user attempts to upload a photo but Photos access is denied */
"Can't Access Photos" = "...";

/* Error description when user attempts to upload a photo but Photos access is denied */
"Make sure to allow photos access for this app in your privacy settings." = "...";

/* Error title when user attempts to take a photo but camera access is denied */
"Can't Access Camera" = "...";

/* Error description when user attempts to take a photo but camera access is denied */
"Make sure to allow camera access for this app in your privacy settings." = "...";

/* Generic error title when user attempts to upload an image and it fails for an unknown reason */
"Can't Retrieve Photo" = "...";

/* Generic error description when user attempts to upload an image and it fails for an unknown reason */
"Please try again or select a new photo." = "...";

/* Error title when user attempts to send the current location but location access is denied */
"Can't Access Location" = "...";

/* Error description when user attempts to send the current location but location access is denied */
"Make sure to allow location access for this app in your privacy settings." = "...";

/* UIAlertView button title to link to Settings app */
"Settings" = "...";

/* UIAlertView button title to dismiss */
"Dismiss" = "...";

/* Title for payment button */
"Pay Now" = "...";

/* Title for message action when payment completed */
"Payment Completed" = "...";

/*
 Instructions for entering credit card info. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
*/
"Enter your credit card to send $%@ %@ securely to %@" = "...";

/* Error text when payment fails */
"An error occurred while processing the card. Please try again or use a different card." = "...";

/* Button label for saved credit card view */
"Change Credit Card" = "...";

/*
 Information label for saved credit card view. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
 */
"You're about to send $%@ %@ securely to %@" = "...";

/* Title for user notification action */
"Reply" = "...";

/* Date format used for message grouping headers on the conversation screen */
"MMMM d, h:mm a" = "MMMM d, h:mm a";

/* Date format used for message timestamps on the conversation screen */
"hh:mm a" = "hh:mm a";

/* Error message when the content of a webview fails to load */
"Failed to open the page" = "...";

会話インタフェースのスタイルの設定

会話のユーザー・インタフェースのスタイルは、次の2つの方法で制御できます:
  • UINavigationBarUIAppearanceプロキシを使用して、ナビゲーション・バーの色と外観のスタイルを設定します。

  • OMCSettingsクラスは、ステータス・バーおよびメッセージ・バブルの色へのアクセスを提供します。

会話UIで黒いナビゲーション・バーと赤いメッセージ・バブルを表示するとします。最初に、UINavigationBarの外観プロキシを使用してナビゲーション・バーを設定します。次に、OMCSettingsを使用してUIのスタイル設定を終了します:
  • Objective C
    OMCSettings* settings = [OMCSettings settingsWithAppId:@"YOUR_APP_ID"];
    settings.conversationAccentColor = [UIColor redColor];
    settings.conversationStatusBarStyle = UIStatusBarStyleLightContent;
    
    [[UINavigationBar appearance] setBarTintColor:[UIColor blackColor]];
    [[UINavigationBar appearance] setTintColor:[UIColor redColor]];
    [[UINavigationBar appearance] setTitleTextAttributes:@{ NSForegroundColorAttributeName : [UIColor redColor] }];
  • Swift
    var settings = OMCSettings(appId: "YOUR_APP_ID");
    settings.conversationAccentColor = UIColor.red();
    settings.conversationStatusBarStyle = UIStatusBarStyle.LightContent
    UINavigationBar.appearance().barTintColor = UIColor.black();
    UINavigationBar.appearance().tintColor = UIColor.red();
    UINavigationBar.appearance().titleTextAttributes = [ NSForegroundColorAttributeName : UIColor.red()];

メニュー・アイテム

iOS SDKには、ユーザーが様々なメッセージ・タイプを送信できるメニューが用意されています。
ios_menu_displayed.pngの説明が続きます

SDKでは、デフォルトでこのメニューが有効になっていますが、メニューを完全に非表示にしたり、そのオプションをカスタマイズすることもできます。
ios_menu_hidden.pngの説明が続きます

メニューの表示を制御するには、OMCESettingsクラスのallowedMenuItems配列をオーバーライドします。メニュー・アイテムを追加または削除することもできます:
// Init Bots Settings
OMCSettings* settings = [OMCSettings settingsWithAppId:appID];
 
 
// You can either disable all options by overwriting the settings with an empty array
settings.allowedMenuItems = nil;
 
 
// OR
// Specify the options accordingly - The options are Camera, Gallery, Document and Location
settings.allowedMenuItems = @[
                              OMCMenuItemCamera,   // Camera
                              OMCMenuItemGallery,  // Photo Gallery
                              OMCMenuItemDocument, // Upload Document
                              OMCMenuItemLocation  // Share Location
                            ];
 
// Then initialize the Bots client with the settings above
[Bots initWithSettings:settings
         completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
        // Your code goes here
 
 
}];

サポートされている機能

デジタル・アシスタントのiOSチャネルでは、次の機能がサポートされています:

  • テキスト(送信と受信の両方)
  • イメージ(送信と受信の両方)
  • ファイル(送信と受信の両方)
  • 絵文字(送信と受信の両方)
  • ロケーション(送信のサポートなし、受信の完全サポート)
  • リンク
  • ポストバック
  • ロケーション・リクエスト
  • カスタム・プロパティ
  • カルーセル・コンポーネント
  • リスト・コンポーネント

メッセージの制約

デジタル・アシスタントのiOSチャネルには、次のようなメッセージの制約があります:

  • テキスト・メッセージ
    • テキスト・アクション・ラベルの最大長: 128文字
    • 許可されるテキスト・アクションのタイプ: ポストバック、URL
    • テキスト・アクションの最大数: 6。テキスト・アクションがこれよりも多い場合、メッセージは複数の水平カードに変換されて、各カードで同じテキストがタイトルとして使用され、各カードに最大6つのアクションが含まれます。
  • 水平カード
    • タイトルの最大長: 30文字
    • 説明の最大長: 128文字
    • カード・アクション・ラベルの最大長: 25文字
    • カードの最大数: 10
    • カード・アクションの最大数: 3。カード・アクションの数が3を超える場合、残りのカード・アクションをレンダリングするためにカードが複製されます。
    • カード・アクションの最小数: 1
    • 説明、イメージまたはアクションが少なくとも1つ必要かどうか: いいえ
    • 許可されるカード・アクションのタイプ: ポストバック、URL
    • 許可されるカード・リスト・アクションのタイプ: ポストバック、URL
  • 垂直カード
    • サポートの有無: いいえ。カードのレイアウトは水平に変換されます。
  • アタッチメント・メッセージ
    • サポートの有無: はい
    • 許可されるアタッチメント・アクションのタイプ: ポストバック、URL
  • アクション・ボタン
    • グローバル・アクション・ラベルの最大長: 128文字
    • 許可されるグローバル・アクションのタイプ: ポストバック、ロケーション

iOSチャネルの拡張機能

iOSチャネルの場合、iOS SDKに固有の機能でSystem.CommonResponseコンポーネントの機能を拡張できます。

拡張機能にアクセスするには、System.CommonResponseコンポーネントのchannelCustomProperties要素を使用し、適切なプロパティを設定します。コードのフォーマットは次のとおりです:

...
            channelCustomProperties:
            - channel: "ios"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

iOSチャネルで使用可能なカスタム・プロパティを次に示します:

名前 許可される値 適用対象 説明
mediaType
  • 有効なメディア・タイプ
  • 次の属性を持つレスポンス・アイテム:
    • type: "attachment"
    • attachmentType: "file"またはattachmentType: "image"
  • imageUrlが指定されたカード
アタッチメントのメディア・タイプ。たとえば、image/jpegです。指定しない場合、メディア・タイプはアタッチメントURLから解決されます。

channelCustomPropertiesの全般的な情報は、チャネル固有の拡張機能を参照してください。