iOSアプリケーションの設定 - iOS SDK

新しいプロジェクトの作成

クライアントが登録されたら、独自のiOSアプリケーションの作成を開始できます。

コマンドラインで、モバイルプロジェクトを作成するディレクトリーに移動し、次のコマンドを実行してください。

以下のユーザー入力を求められます。

1. モバイルアプリの名前（見込み客の承認者など）。
2. iOS開発者の組織名。
3. iOS開発者の組織ID。
4. Zoho OAuthクライアントID（アプリ登録時に取得）。
5. Zoho OAuthクライアントシークレット（アプリ登録時に取得）。
6. Zoho OAuthリダイレクトURL（アプリ登録時に取得）。

上記のコマンドを正常に実行すると、プロジェクトフォルダーが同じディレクトリーに作成されます。プロジェクトフォルダーの名前は、モバイルアプリの名前と同じになります。

プロジェクトの実行

新しく作成されたプロジェクトは、実際にはiOSアプリのデモであり、Xcodeを使用してすぐに実行できます。

1. 新しく作成したプロジェクトの.xcWorkspaceファイルを開きます。
   新しく作成したデモアプリを、Xcodeプロジェクトとして開きます。
2. 正常にコンパイルされると、このプロジェクトをシミュレーターにかんたんに実行できます。
   このアプリは、シミュレーターのZohoサインイン画面で開きます。
3. Zoho CRM認証情報でサインインし、デモアプリでデータを表示できます。

アプリの拡張

プロジェクトが正常にビルドされ実行されると、要件に応じて、アプリ用の新しい画面と機能をさらに設計して作成できます。アプリの開発には、フロントエンドの制限はありません。ただし、ユーザー認証をかんたんにするために、アプリの設計時には次の点に注意してください。

AppDelegate.swiftにすでに存在するコードは変更しないでください。

サインイン/サインアウトを処理するには：

ユーザーサインインを適切に処理するために、起動画面はSDKですでに設定されており、サインインしているユーザーだけがアプリケーションのデータを表示できるようになっています。ただし、独自にカスタマイズしたサインイン画面を表示する場合は、独自のビューを起動画面として宣言できます。

カスタム起動画面のViewControllerクラスで、次のコードを［サインイン］ボタンのアクションとして追加してください。

次のコードを［サインアウト］ボタンのアクションとして追加してください。

AppConfiguration.plistファイルの場合

1. OAuthScopes（必須） - 作成されたプロパティーファイルにサンプルスコープがすでに記述されており、必要に応じてスコープを変更できます。詳しくはこちらを参照してください。
2. AccessType（オプション） - CRMの環境のタイプ
   • 本番 - 重要なビジネスデータにアクセスする有効な有料ユーザーが存在する環境。
   • 開発 - 本番環境に影響を与えることなく拡張、連携、開発が可能な環境。
   • サンドボックス - 本番環境に展開する前、またはお客さまにリリースする前に、アプリケーションの機能をテストするための専用の環境。
3. DomainSuffix（オプション） - 複数DCサポート。
   • us - www.zohoapis.com
   • eu - www.zohoapis.eu
   • cn - www.zohoapis.com.cn
4. PortalID（オプション） - CRM PortalIDを指定してください（例：65468393）。"PortalID"がない場合は、プロパティーファイル内で指定する必要はありません。
5. ShowSignUp（オプション）- アプリケーションにサインアップ機能を提供する場合はtrue、それ以外の場合はfalseを指定してください。

このファイルには、アプリの実行に必要な特定の構成の値が含まれています。プロパティーの既存の名前や値は、SDKとアプリをスムーズに機能させるために必要なので変更しないでください。

Zoho CRM APIラッパー

Zoho CRMのすべてのエンティティーは、その特定のエンティティーに適用可能なメンバーとメソッドを持つクラスとしてモデル化されます。ZCRMRestClientは、クライアントライブラリーの基本クラスです。

ライブラリーのクラス関係と階層は、Zoho CRM内のエンティティー階層に従います。さまざまなZoho CRMエンティティーのクラス階層を以下に示します。

階層に表示されるように、すべてのエンティティークラスには、API呼び出しを通じて、独自のプロパティーとの直下の子エンティティーのデータを取得するためのメソッドがあります。

たとえば、Zoho CRMタブ（ZCRMModule）オブジェクトには、表示名、タブIDなどのタブのプロパティーと、すべての子レイアウト（ZCRMLayout）オブジェクトを取得するメソッドがあります。

データのプロパティーへのアクセス

データのプロパティーはタブごとに異なるため、ZCRMRecordのデフォルトメンバーとして、CreatedTime、CreatedBy、Ownerなどの共通項目のみが指定されています。その他のすべてのデータのプロパティーは、ZCRMRecordオブジェクトのマップとして使用できます。

データの個々の項目値にアクセスするには、使用可能なgetterメソッドとsetterメソッドを使用してください。データのプロパティーのマップのキーは、タブの項目のAPI名です。すべてのタブのすべての項目のAPI名は、［設定］> ［開発者向け情報］ > ［API］ > ［CRM API］ > ［API名］で使用できます。

• 項目値を取得するには、record.getFieldValue(fieldAPIName);を使用してください。
  返される値は、リクエストされた項目のAPTデータ型になります。ルックアップ項目とユーザーの種類の項目の場合、ZCRMRecordオブジェクトとZCRMUserオブジェクトがそれぞれ返されます。
• 項目値を設定するには、record.setFieldValue(fieldAPIName, newValue);を使用してください。
  項目値を設定する際、設定値が、設定する項目のaptデータ型であることを確認してください。

提供される拡張機能：

文字列内：

• dateFromISO8601 : Date?
• dateComponents : DateComponents

日付内：

• iso8601 : String
• millisecondsToISO( timeIntervalSince1970 : Double, timeZone : TimeZone ) -> String
• millisecondsToISO( timeIntervalSinceNow : Double, timeZone : TimeZone ) -> String
• millisecondsToISO( timeIntervalSinceReferenceDate : Double, timeZone : TimeZone ) -> String
• millisecondsSince1970 : Double
• dateComponents : DateComponents

ユーザーのプロフィール画像をダウンロードするには：

ダウンロードするためにSDKで使用できるメソッドは次のとおりです。

• ZCRMUser().downloadProfilePhoto()
• ZCRMUser().downloadProfilePhoto( size : PhotoSize )

レスポンス処理

APIResponseとBulkAPIResponseは、Zoho CRM APIのレスポンスのラッパーオブジェクトです。すべてのAPI呼び出しメソッドは、これら2つのオブジェクトのいずれかを返します。

単一のエンティティーを検索するメソッドはAPIResponseオブジェクトを返し、エンティティーの一覧を検索するメソッドはBulkAPIResponseオブジェクトを返します。

getData()メソッドを使用して、エンティティーデータのみをレスポンスラッパーオブジェクトから取得してください。APIResponse.getData()は、単一のZoho CRMエンティティーオブジェクトを返し、BulkAPIResponse.getData()は、Zoho CRMエンティティーオブジェクトのリストを返します。

これらのレスポンスラッパーオブジェクトには、データ以外に次のプロパティーがあります。

1. ResponseHeaders - 現在の日付/ウィンドウの残りのAPIカウントと、現在のウィンドウがリセットされてから経過した時間。
2. ResponseInfo - 実際のデータと、その他の情報（APIによって提供される場合）。
3. [EntityResponse] - 一括APIの個々のエンティティーのステータス。たとえば、データの追加では、いくつかのデータのためにAPIが部分的に失敗することがあります。この一覧は、個々のデータの作成ステータスを示してください。

エラー

問題のあるAPIレスポンス、ライブラリー異常などの予期しない動作はすべてクライアントライブラリーによって処理され、aptエラーの場合はZCRMSDKErrorとしてのみスローされます。したがって、このエラーを検出するにはクライアントアプリコードだけで十分です。

SDKデータアクセスラッパー

Zoho CRM APIの上記のラッピングに加えて、不要なAPI呼び出しを回避するために、必須のタブメタデータがSDKによってデバイスのローカルストレージにキャッシュされます。

現在、CRMデータ（レコード）はキャッシュされず、レイアウト、セクション、項目、カスタムビューの詳細などのタブのメタデータのみがキャッシュされます。

ZCRMCachedModule

一部の追加のメタデータキャッシングは、ZCRMCachedModuleによって行われます。これにより、Zoho CRM APIクライアントライブラリーのZCRMModuleクラスが拡張されます。このクラスには、次のメソッドがあります。

• getAllLayouts - タブのすべてのレイアウトをZCRMLayoutの配列として返します。
• getAllCustomViews - タブのすべてのカスタムビューの詳細をZCRMCustomViewの配列として返します。

キャッシュの更新

ZCRMCachedModuleは、デバイスのローカルストレージにキャッシュされているタブとフォームレイアウトのメタデータ情報を保存して使用してください。SDKは、タブの保存されたメタデータを12時間ごとにリフレッシュしてください。

Zoho CRM API呼び出しを通じて、SDKにキャッシュの削除（例：アプリでリフレッシュするためにスワイプのようなものを提供したい場合）とメタデータのリフレッシュを実行したい場合は、上記のメソッドのオーバーロードされたバージョンで提供されているrefreshCacheフラグを設定することで実行できます。以下に、呼び出しの例を示します。