Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

@amazon-devices/recommendation-manager

@amazon-devices/recommendation-manager

Amazon Media Recommendations APIは、クライアントアプリがAmazonデバイス上でおすすめを追加および削除できるようにするサービスです。これらのおすすめはデバイスのホーム画面に表示され、パーソナライズされたコンテンツの候補をユーザーに提供します。このAPIは、ユーザーエクスペリエンスの向上を目的に設計され、ユーザーの好みや視聴履歴に基づいて関連性の高い魅力的なおすすめを提示できます。

このAPIには、次の2つの実装が含まれています。

  • RecommendationManager
  • RecommendationManager2

APIのバージョン2.x.x以降、新しいアプリではRecommendationManager2の実装を使用しておすすめを送信する必要があります。この実装では、コンテンツ画像のバイト配列とコンテンツ画像のURIを介してコンテンツ画像がサポートされます。古いアプリについては、RecommendationManager2にアップデートして拡張機能を使用することをおすすめします。

開始の手順

パーミッション

APIには、権限の使用による認証が必要です。具体的には、APIにアクセスしておすすめを追加するのにcom.amazon.privilege.security.file-sharingの権限が必要になります。

セットアップ

  1. package.jsonファイルのdependenciesセクションに、以下のライブラリ依存関係を追加します。

    クリップボードにコピーしました。

       "@amazon-devices/recommendation-manager": "~2.0.2"2.

  2. manifest.tomlに、以下の権限を追加します。

    クリップボードにコピーしました。

     [wants]
 [[wants.service]]
 id = "com.amazon.recommendation.service.main"

 [[needs.privilege]]
 id = "com.amazon.privilege.security.file-sharing"

使用方法

おすすめの追加

  1. 必須フィールド（タイトル、テキスト、コンテンツ画像、カテゴリ、表示名、表示アクションオプションなど）を含むRecommendation2オブジェクトを作成します。
  2. RecommendationManager2クラスのaddRecommendations2メソッドを呼び出し、Recommendation2オブジェクトの配列を渡します。
  3. このメソッドは、新しく追加されたおすすめを表す数値の配列を返します。各番号はおすすめに対応しており、今後そのおすすめを削除する際に使用できます。
    • コンテンツ画像のバイト配列を指定すると、画像はすぐにデバイスに保存されます。
    • コンテンツ画像のURIが指定されている場合、画像は非同期でダウンロードされます。画像のダウンロードに失敗すると、おすすめはAmazonデバイスから削除され、コンテンツ画像のURIのダウンロードが失敗したことを示すエラーメッセージがAmazonデバイスに記録されます。

注： コンテンツ画像のバイト配列とコンテンツ画像のURIの両方が指定されている場合、RecommendationManager2はデフォルトでコンテンツ画像のバイト配列を使用します。

注： React Native URLコンストラクターは、URLの末尾に/を自動的に追加します。これにより、コンテンツ画像のURIのダウンロードが失敗する可能性があります。この問題を回避するには、以下の手順に従います。

  1. 標準のURLコンストラクターを使用してURLを作成します。
  2. _urlフィールドを、希望する正確なURL文字列に手動で設定します。

クリップボードにコピーしました。

  const imageUrl = new URL('https://example.com/image.png');
  (imageUrl as any)._url = 'https://example.com/image.png';  // 末尾のスラッシュを削除します

  // Recommendation2オブジェクト内
  contentImageUri: imageUrl

この問題は、おすすめマネージャーの今後のバージョンで対処される予定です。おすすめマネージャーは標準URLオブジェクトの特定のフィールドを必要とするため、代替のURL解析ライブラリ（react-native-url-polyfillなど）とは互換性がないことに注意してください。

例：

クリップボードにコピーしました。

import {
    RecommendationManager2,
    Recommendation2,
    Category,
    DisplayAction,
    InvalidArgumentError,
    SecurityError,
} from '@amazon-devices/recommendation-manager';

const recommendationWithContentImageByteArray : Recommendation2 = {
    title: 'Recommended Movie1',
    text: 'Check out this great movie!',
    contentImageUri: new URL(<content image uri>),
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
};
const recommendationWithContentImageUri : Recommendation2 = {
    title: 'Recommended Movie2',
    text: 'Check out this great movie!',
    contentImage: [/* image data */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
}

const recommendations: Recommendation2[] = [
    recommendationWithContentImageUri,
    recommendationWithContentImageByteArray
];

try {
    const addedIds = RecommendationManager2.addRecommendations(recommendations);
        console.log('Added recommendations:', addedIds);
    } catch (e) {
        if (e instanceof SecurityError) {
            console.error('Security error:', e.message);
        } else if (e instanceof InvalidArgumentError) {
            console.error('Invalid argument error:', e.message);
        } else {
            console.error('Error adding recommendations:', e);
        }
    }

おすすめの削除

  1. 特定のおすすめを削除するには、RecommendationManager2クラスのremoveRecommendations()メソッドを呼び出して、削除するおすすめを表す数字の配列を渡します。
  2. クライアントアプリケーションから送信されたすべてのおすすめを削除するには、RecommendationManager2クラスのremoveAllRecommendations()メソッドを呼び出します。

例：

クリップボードにコピーしました。

// おすすめを削除します
RecommendationManager.removeRecommendations([addedIds[0]]);

// すべてのおすすめを削除します
RecommendationManager.removeAllRecommendations();

レガシーユースケース（バージョン1.x.x）

おすすめの追加

  1. 必須フィールド（タイトル、テキスト、コンテンツ画像、カテゴリ、表示名、表示アクションオプションなど）を含むRecommendationオブジェクトを作成します。
  2. RecommendationManagerクラスのaddRecommendations()メソッドを呼び出し、Recommendationオブジェクトの配列を渡します。
  3. このメソッドは、新しく追加されたおすすめを表す数値の配列を返します。各番号はおすすめに対応しており、今後そのおすすめを削除する際に使用できます。

サンプル：

クリップボードにコピーしました。

import RecommendationManager, { Category, DisplayAction, Recommendation } from './RecommendationManager';

const recommendations: Recommendation[] = [
  {
    title: 'Recommended Movie',
    text: 'Check out this great movie!',
    contentImage: [/* image data */],
    backgroundImageUri: new URL('https://example.com/background.png'),
    contentUri: new URL('(`orpheus://component-id-of-app-hosting-the-content`'),
    category: Category.HOME,
    displayName: 'Movie App',
    displayActionOption: DisplayAction.WATCH_WITH_APP_DISPLAY_NAME,
    maturityRating: 'PG',
    customerAggregateRating: 8,
    customerRatingCount: 100,
    runningTime: 120,
    releaseYear: 2022,
    isCaptionAvailable: true,
  },
];

try {
  const addedIds = RecommendationManager.addRecommendations(recommendations);
  console.log('Added recommendations:', addedIds);
} catch (e) {
  if (e instanceof SecurityError) {
    console.error('Security error:', e.message);
  } else if (e instanceof InvalidArgumentError) {
    console.error('Invalid argument error:', e.message);
  } else {
    console.error('Error adding recommendations:', e);
  }
}

おすすめの削除

  1. 特定のおすすめを削除するには、RecommendationManager2クラスのremoveRecommendations()メソッドを呼び出して、削除するおすすめを表す数字の配列を渡します。
  2. クライアントアプリケーションから送信されたすべてのおすすめを削除するには、RecommendationManagerクラスのremoveAllRecommendations()メソッドを呼び出します。

サンプル：

クリップボードにコピーしました。

// おすすめを削除します
RecommendationManager.removeRecommendations([addedIds[0]]);

// すべてのおすすめを削除します
RecommendationManager.removeAllRecommendations();

おすすめフィールドの説明は以下の通りです

フィールド 型 説明 必須
title string おすすめのコンテンツタイトル。 ×
text string おすすめの概要テキスト。 ×
contentImage number[] このおすすめに表示される画像（PNG）。おすすめ画像の仕様が正しくない場合は、addRecommendations()メソッドを呼び出すときにInvalidArgumentErrorが発生します。使用可能な画像形式の詳細については、許容される画像仕様を参照してください。 ○
contentImageUri URL このおすすめで表示される画像（PNG）の取得に使用されるURI。おすすめ画像の仕様が正しくない場合は、addRecommendations()メソッドを呼び出すときにInvalidArgumentErrorが発生します。使用可能な画像形式の詳細については、許容される画像仕様を参照してください。 ○
backgroundImageUri URL おすすめの背景画像を取得するために使用するURI。この画像は、ユーザーがおすすめアイテムにカーソルを合わせると表示されます。 ×
contentUri URL ユーザーがおすすめをクリックしたときに起動されるURI。 ×
category Category おすすめのカテゴリ（[ホーム]、[マイビデオ]、[ライブ]、[UHD]など）。 ○
displayName string （おすすめを選択した状態でメニューボタンを押した場合に）起動メニューに表示されるアプリの略称。 ×
displayActionOption DisplayAction 各おすすめに表示される最初のコンテキストメニューオプションを決定します。 ○
maturityRating string タイトルの下に年齢別レーティングが表示されます。許容される年齢別レーティングの詳細については、サポートされている年齢別レーティングの値を参照してください。 ○
customerAggregateRating number すべてのユーザーからの評価を集計します。指定できる値の範囲は0～10です。 ×
customerRatingCount number このコンテンツを評価したユーザーの数。0に設定すると、コンテンツは未評価とみなされます。 ×
runningTime number コンテンツの実行時間（分単位）（該当する場合）。ライブコンテンツではこれを0に設定できます。 ×
releaseYear number コンテンツのリリース年。例： 2016、2015。 ×
isCaptionAvailable boolean キャプションがコンテンツで利用できるか（true）、できないか（false）を示します。falseは、コンテンツにキャプションがないことを意味します（デフォルト）。trueは、コンテンツにキャプションが表示されることを意味します。 ×

許容される画像仕様

  • 縦横比： 16:9
  • チャンネル： 3（BGR）、8ビット/チャンネル
  • 向き： 横向き
  • 形式： PNG
  • ディスプレイに応じて、画像の解像度は次のようになります。
    • HDTV（720p）： 256 * 144
    • HDTV（1080p）： 384 * 216
    • 4K UHD： 768 * 432
  • Title: 画像内に埋め込み
  • 透明性： 不透明

サポートされている年齢別レーティングの値

  • 米国のマーケットプレイス： G、PG、PG13、R、NC17、NR、TVY、TVY7、TVG、TVPG、TV14、TVMA
  • ドイツのマーケットプレイス： FSK0、FSK6、FSK12、FSK16、FSK18
  • 英国のマーケットプレイス： BBFCPG、BBFC12、BBFC18、BBFCU
  • 日本のマーケットプレイス： EIRIN_G、EIRIN_PG12、EIRIN_R15、EIRIN_18
  • インドのマーケットプレイス： ALL、7+、13+、16+、18+、NR

トラブルシューティング

  • SecurityError: このエラーは、呼び出し元のアプリケーションに必要な com.amazon.privilege.security.file-sharingの権限がない場合に発生します。APIを呼び出す前に、アプリケーションに必要な権限があることを確認してください。
  • InvalidArgumentError: このエラーは、次のシナリオで発生する可能性があります。
    • おすすめオブジェクトのサイズが512KBを超えている（コンテンツ画像サイズを除く）。
    • Recommendationオブジェクトの必須フィールドが空または無効である。
    • コンテンツ画像が、指定された寸法とサイズの要件を満たしていない。
    • addRecommendations()に渡されるおすすめの配列のサイズが20を超えている。

  • おすすめが表示されない場合：

    • コンテンツ画像のURIフローが使用されている場合、画像のダウンロードに失敗していないか確認してください。画像のダウンロードに失敗した場合、おすすめは追加されません。デバイスログには、画像のダウンロードが失敗したことが示されます。以下に例を示します。

      Failed to fetch image for recommendation.Ignoring it.

    • 一意の行IDを使用して、おすすめがおすすめマネージャーのデータベースに正常に追加されたかどうかを確認します。一意の行IDはログで確認できます。

      recommendation_[4509]: 8 I recommendationCommonLib:[log_impl.cpp:14] Recommendations are for config: <一意の行ID>

      一意の行IDを見つけたら、上記の一意の行IDに対応する構成ファイルを確認します。このファイルには、行に正常に追加されたおすすめが含まれています。このファイルが空の場合、呼び出し元アプリのおすすめが追加されていないことを意味します。addRecommendationsを呼び出すときは、デバイスログでエラーログを確認してください。

      クリップボードにコピーしました。

      adb shell cat /home/app_user_packages/com.amazon.recommendation.service/data/<一意の行ID>

モジュール

Last updated: 2025年10月2日

フォローする

サポート対象デバイス

amazon_developer_logo

© 2010-2025, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ