これは、コンテンツアイテムをLiftIgniterの[インベントリ]に登録するための[POST]リクエストです。
定義
ドキュメント
[インベントリ]は、LiftIgniterでトラックする[アイテム]です。 ここに登録された[アイテム]がリコメンデーションに使用されます。
Webサイトへの組み込みにおいては、通常では[url]のフィールドをインベントリIDのフィールドとして使用します。このフィールドをインベントリアイテムのプライマリキーとして使用できます。
使用のケースによって"url"のフィールドが、ユニークなフィールドとしての使用に適していないと考えられる場合は、ご連絡ください。インベントリIDのフィールドの名称を変更します。これは、インベントリの送信を開始する前にご連絡ください。
アイテムの追加および削除は、インベントリIDのフィールドを使用して行われます。このフィールドが存在しない場合は、リクエストが拒否されます。アイテムを追加する際に、同じインベントリIDを持つアイテムが存在する場合は、そのアイテムを上書きして追加されます。
大量のインベントリ書き込み制限
インベントリの書き込みについて下記の事項を推奨します:
- 同時に複数の[インベントリアイテム]を書き込む場合は、約1000件のバッチサイズを目安にしてください。バッチサイズの最大制限数は10,000件ですが、少ない件数で書き込むことを推奨します。
- 一般的に、一分間に20,000件までの書き込みを処理することができますが、実際は一分間に10,000件以内にすることを推奨します。
詳細はレートの制限に関するドキュメントを参照してください。
サポートしているインベントリタイプ
LiftIgniterは、下記の値を
[インベントリアイテム]としてサポートしています:
- 文字列
- 文字列のリスト
- 数値
現在は、[インベントリアイテム]はNested JSON（入れ子状のJSON）に対応していません。入れ子の構造にされたアイテムは、インベントリをスクレープする際に無視されます。
書き込みもアップデートとして機能しますが、既存のアイテムより完全に優先されます
[インベントリアイテム]を書き込む際に、既に同じアイテムがデータに存在している場合は、新しく書き込んだアイテムで上書きします。アイテムは新たにフィールドを追加するのではなく、完全に上書きします。
特殊なフィールド名
システムは、下記の特別な処理を行うフィールド名をサポートしています。これらのフィールド名だけに限定して使用する必要はありませんが、LiftIgniterではこれ以外のフィールド名の意味を正常に判断することができません。その場合はお客様と別途打ち合わせを行う必要があります。
- ユニーク識別子のフィールド名（デフォルトでは
[url]を設定）は、アイテムを指定するために使用します。他のアイテムを同じユニーク識別子の値で書き込むと、既存の値は上書きされます。 [title]は、アイテムのタイトルを指定するために使用します。ユーザのアクティビティは、より重要な役割を果たしますが、タイトルの類似性もひとつのメタデータのシグナルとして扱われます。これは、すべてのお客様にデフォルトで同様の処理を行います。[thumbnail]と[image]は、オブジェクトの画像を指定するために使用します。Modelクエリがthumbnailをリクエストしても[thumbnail]が指定できない場合は、[image]の値が返されます。[description]は、コンテンツの詳細説明として使用します。 titleと同様にメタデータのシグナルのとして使用されますが、titleよりは重要性が低く扱われます。- インデックスは、
[tag]、[category]、[channel]、[type]のフィールドをもとに構築します。これらのフィールド名を使用して、フィールド名が一致するアイテムのクエリを送信するルールを設定することができます。 [published_time]および[modified_time]のフィールド名を使用して、コンテンツの投稿時刻と最終更新時刻を得ることができます。（時刻はOpen Graph protocolのISO 8601のフォーマット）この仕様は、多くのお客様がJacascriptを使用したスクレーピングを用い、既にメタデータを持ちあわせていることから採用しました。[noShow]の値を"true"に設定することで、LiftIgniterが表示できないアイテムをマークできます。
インベントリ操作時のタイムラグ
インベントリのアップデートや削除は、即時で処理されない場合があります。
アイテムの書き込みとクエリの送信の間で、最低でも1分から5分の処理遅延が発生することを想定してします。
アイテムへのクエリを送る場合は、インベントリGET endpointを使用することができます。
リコメンデーションにアイテムが表示されるまでに、最大10分程度の遅延が発生することを想定してください。
処理の順番は保証していません。近いタイミング（1分間以内）で行われた書き込みと削除の処理の処理順番は予想ができません。
インベントリアップデートの自動設定
インベントリアップデートを自動で行うためには3つの方法があります:
- 随時アップデート: お客さまのシステム側でアップデートが発生（新しい記事や動画が投稿または削除された、既存のアイテムのメタデータが変更されたなど）するごとにインベントリAPI endpointにアップデートを送信します。そうすることでシステムのインベントリメタデータは最新のものに保たれます。この方法の欠点は、お客様または我々のいずれかのシステムで問題が発生した場合、我々のシステム側に正常にないデータを永久に保持してしまうことです。
- 定期同期: 定期的に（1日1〜2回）すべてのインベントリを送る。
- アップデートされたコンテンツに対する定期同期: 定期的にアップデートされた（追加、編集または削除された）インベントリアイテムだけを送る。
必要に応じていずれかの方法を選択してください。頻繁にコンテンツの更新を行い、即時に反映させたい場合は、随時アップデートの方法を選択してください。もし更新の内容がリアルタイムで反映させるほど重要ではない場合は、定期同期の方法を選択してください。または、定期同期にあわせて随時アップデートを行うことも可能です。
インベントリのアップデートが成功したか確認する場合（特に重要なアップデートの場合など）は、 アップデートの数分後にGET endpointを使用して処理結果確認を行ってください。
Javascriptによるインベントリ書き込みの動作
多くのお客様が、LiftIgniterのJavascriptを使用してインベントリのアップデートを行っています。ユーザがLiftIgniterビーコンを組み込んだWebサイトを閲覧すると、Javascriptを使用してインベントリを収集します。これは、インベントリ POST endpointの代替となる方法です。
我々のシステムバックエンドは、書き込みがJavascriptとAPIのどちらを使用して行われたかを区別しません。（ただしデバッグ目的としてログには記録されます）どちらの方法でも、同じ領域にあるインベントリのアップデートが行われます。
ここでは、JavascriptかインベントリPOST endpointのいずれかひとつの方法を採用することを推奨します。2つの方法を混在させることにより、JavascriptがPOSTの動作を妨害して、処理に混乱を来す可能性があります。
インベントリ書き込みのトラッキング
インベントリ書き込みの履歴（特に書き込みを行ったインベントリの数など）を確認したい場合は、LiftIgniter Labのインベントリパネルを参照してください。"api_ins"のフィールドに、APIを通じて行ったインベントリの書き込みを記録しています。Javascriptを通じて行ったインベントリの書き込みは、pixel_insに区別して記録されます。