REST API ব্যবহার করে সাজেশন ইন্টিগ্রেট করা

Google TV ভিডিও ডিসকভারি REST API পার্টনারদের তাদের ব্যাকএন্ড সার্ভার থেকে Google TV এবং Android TV ডিভাইসে পছন্দমতো নয় এমন সাজেশন ক্যান্ডিডেট পাঠাতে দেয়। ব্যাকএন্ড থেকে ক্যান্ডিডেট পাঠানোর ফলে, ব্যবহারকারীকে পার্টনারের অ্যাপ না খুলেই, এইসব ডিভাইসে পার্টনারের ক্যাটালগ ও লাইভ প্রোগ্রামিং সংক্রান্ত সাজেশন আপ-টু-ডেট রাখা যায়।

পার্টনাররা সাজেশন ফিডে ক্যান্ডিডেট পাঠান। Google পার্টনারের জন্য প্রতিটি ফিড তৈরি করে এবং দেশ বা অঞ্চল এবং টিভি ডিভাইসের ভাষা কনফিগার করে যেখানে ফিড দেখানো হয়। ফিডে সিনেমা, টিভি শো ও লাইভ টিভি প্রোগ্রাম থাকতে পারে।

ব্যবহারকারীর ডিভাইস থেকে পছন্দমতো সাজেশন প্রকাশ করতে চাইলে, Engage SDK ব্যবহার করে অন-ডিভাইস সাজেশন ইন্টিগ্রেট করুন দেখুন।

পূর্বশর্ত

REST API-এর সাথে ইন্টিগ্রেট করার আগে, আপনার কাছে নিম্নলিখিতগুলি আছে কিনা তা নিশ্চিত করুন:

  • API অনুরোধ করার জন্য একটি Google Cloud প্রোজেক্ট।
  • আপনার সংস্থার সাথে যুক্ত একটি Google Workspace অ্যাকাউন্ট।
  • আপনার পার্টনার আইডি এবং সাজেশন ফিড আইডি, যা অনবোর্ডিংয়ের সময় আপনার Google TV পার্টনার প্রতিনিধি প্রদান করেছেন। এইসব আইডি কীভাবে ব্যবহার করা হয় তা জানতে সাজেশন ফিড দেখুন।

অ্যাক্সেস পান

Google TV ভিডিও ডিসকভারি REST API-তে অ্যাক্সেস রেজিস্টার করা Google TV মিডিয়া পার্টনারদের জন্য সীমিত করা হয়েছে। প্রতিটি কলারকে Google Cloud পরিষেবা অ্যাকাউন্ট ব্যবহার করে যাচাই করা হয় যা সার্ভারে ঠিক একটি পার্টনার আইডিতে ম্যাপ করা হয়।

API অ্যাক্সেসের অনুরোধ ও কনফিগার করতে, এই ধাপগুলি অনুসরণ করুন:

  1. Google Workspace অ্যাকাউন্ট তৈরি করুন। আপনার সংস্থার জন্য অ্যাকাউন্ট সেট-আপ করতে Google Workspace সহায়তা পৃষ্ঠায় দেওয়া নির্দেশাবলী অনুসরণ করুন।
  2. আপনার Google Workspace কাস্টমার আইডি খুঁজে নিন। আপনার কাস্টমার আইডি খুঁজুন লিঙ্কে দেওয়া ধাপগুলি অনুসরণ করে আপনার কাস্টমার আইডি (যেমন, C0123abcd) খুঁজুন।
  3. Google Cloud প্রোজেক্ট ও পরিষেবা অ্যাকাউন্ট তৈরি করা। আপনার Google Workspace প্রতিষ্ঠানের অধীনে Google Cloud Console-এ, আপনার ব্যাকএন্ড সার্ভারের জন্য একটি Google Cloud প্রোজেক্ট এবং একটি পরিষেবা অ্যাকাউন্ট তৈরি করুন।
  4. পার্টনার অনবোর্ডিংয়ের অনুরোধ করুন। আপনার Google Workspace কাস্টমার আইডি, Google Cloud প্রোজেক্ট আইডি এবং পরিষেবা অ্যাকাউন্টের ইমেল আইডি (বা অনন্য সংখ্যাসূচক আইডি) আপনার Google TV পার্টনার প্রতিনিধির কাছে জমা দিন, এর সাথে আপনি যে দেশ বা অঞ্চল এবং টিভি ডিভাইসের ভাষায় ক্যান্ডিডেট পাঠাতে চান তাও জানান। আপনার Google TV পার্টনার প্রতিনিধি আপনার Google Workspace সংস্থা, প্রোজেক্ট এবং পরিষেবা অ্যাকাউন্ট আপনার পার্টনার আইডিতে ম্যাপ করার পরে আপনাকে বিজ্ঞপ্তি দেয় এবং আপনার পার্টনারের জন্য তৈরি করা সাজেশন ফিড আইডি আপনাকে দেয়।
  5. API চালু করুন এবং ক্রেডেনশিয়াল তৈরি করুন। আপনার প্রতিনিধি অ্যাক্সেস মঞ্জুর করা হয়েছে বলে কনফার্ম করার পরে, আপনার Google Cloud প্রোজেক্টে Google TV ভিডিও ডিসকভারি API (tvvideodiscovery.googleapis.com) চালু করুন এবং আপনার পরিষেবা অ্যাকাউন্টের জন্য OAuth 2.0 ক্রেডেনশিয়াল জেনারেট করুন।
  6. আপনার অনুরোধ যাচাই করুন। নিম্নলিখিত OAuth স্কোপ ব্যবহার করে OAuth 2.0 অ্যাক্সেস টোকেনের জন্য অনুরোধ করুন এবং প্রতিটি কলে Authorization: Bearer HTTP হেডারে টোকেনটি পাস করুন:

    https://www.googleapis.com/auth/tvvideodiscovery
    

রেটের সীমা

replaceCandidates-এ করা অনুরোধগুলি নিম্নলিখিত প্রোজেক্ট-প্রতি রেট সীমা এবং অনুরোধ-প্রতি পেলোড ক্যাপের সাপেক্ষে:

সীমা মান
প্রতি Google Cloud প্রোজেক্টে প্রতি মিনিটে অনুরোধের সংখ্যা 5
প্রতিদিন প্রতিটি Google Cloud প্রোজেক্টে করা অনুরোধের সংখ্যা 100
প্রতিটি অনুরোধে RecommendationCandidateটি আইটেম ১ থেকে ২৫

স্টেজিং ফিডে করা অনুরোধ, সংশ্লিষ্ট প্রোডাকশন ফিডে করা অনুরোধের মতো একই কোটার বিপরীতে গণনা করা হয়।

সাজেশন ফিড

API, সাজেশন ফিডে সাজেশন ক্যান্ডিডেটদের সাজায়। একটি ফিড নিম্নলিখিত ফর্ম্যাটে রিসোর্সের নাম দ্বারা শনাক্ত করা হয়:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

পার্টনার

{partner} হল পার্টনার আইডি যা অনবোর্ডিংয়ের সময় Google আপনাকে অ্যাসাইন করে। আপনি যে পরিষেবা অ্যাকাউন্ট যাচাই করেন সেটি ঠিক একটি পার্টনার আইডিতে ম্যাপ করা হয়। অন্য কোনও পার্টনারের নাম উল্লেখ করে করা অনুরোধ 403 PERMISSION_DENIED-এর সাথে ব্যর্থ হয়।

ফিড আইডি

{recommendationsFeed} হল একটি ফিড আইডি যা Google আপনার জন্য অনবোর্ডিংয়ের সময় তৈরি করে। আপনি API-এর মাধ্যমে ফিড তৈরি করতে পারবেন না।

প্রতিটি ফিড এমন দর্শকদের টার্গেট করে যাদের Google ফিড তৈরি করার সময় কনফিগার করে:

  • দেশ বা অঞ্চল: যেখানে ফিডের প্রার্থীকে দেখানো হয়।
  • টিভি ডিভাইসের ভাষা: টার্গেট করা ব্যবহারকারীরা তাদের টিভি ডিভাইসে যে ভাষা সেট করেছেন। আপনি যে টেক্সট পাঠান, এটি সেই ভাষা নয়। একাধিক ভাষায় টেক্সট প্রদান করতে, LocalizedString দেখুন।

Google TV এবং Android TV ডিভাইসে ফিডের ক্যান্ডিডেট কোথায় দেখানো হবে তা Google ঠিক করে। আপনি একই পদ্ধতিতে প্রতিটি ফিডে ক্যান্ডিডেট পাঠান।

স্টেজিং ফিড

প্রতিটি ফিডের সাথে {recommendationsFeed}-staging নামের একটি ম্যাচিং স্টেজিং ফিড আছে। স্টেজিং ফিড শুধুমাত্র অনুমোদিত তালিকায় থাকা টেস্ট অ্যাকাউন্টে দেখানো হয়। প্রোডাকশন ফিডে প্রার্থী পাঠানোর আগে আপনার ইন্টিগ্রেশন যাচাই করতে এটি ব্যবহার করুন।

স্টেজিং ফিড প্রোডাকশন ফিডের মতো একই এন্ডপয়েন্ট, ক্রেডেনশিয়াল, অনুরোধ যাচাইকরণ এবং কোটা ব্যবহার করে। শুধু দর্শক আলাদা।

পরিবর্তন

ফিড হল রিপ্লেসমেন্টের ইউনিট। প্রতিটি replaceCandidates কল সেই ফিডের জন্য আগে থেকে স্টোর করা সব ক্যান্ডিডেটকে প্রতিস্থাপন করে এবং অন্য প্রতিটি ফিডকে অপরিবর্তিত রাখে।

সাজেস্ট করা ক্যান্ডিডেট পরিবর্তন করুন

একটি ফিডের জন্য সাজেস্ট করা ক্যান্ডিডেটের সম্পূর্ণ তালিকা পাঠাতে partners.recommendationsFeeds.replaceCandidates পদ্ধতি ব্যবহার করুন।

HTTP অনুরোধ

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

URL পাথে ফিডের রিসোর্স নাম থাকে যার ক্যান্ডিডেট পরিবর্তন করা হয়েছে। অনুরোধের প্রধান অংশে URL পাথের অংশ নয় এমন প্রতিটি ফিল্ড থাকে।

পাথ প্যারামিটার

প্যারামিটার বর্ণনা
name প্রয়োজনীয়। partners/{partner}/recommendationsFeeds/{recommendationsFeed} ফর্ম্যাটে ফিডের রিসোর্স নাম। {partner} অবশ্যই পার্টনার আইডি হতে হবে যার সাথে আপনার পরিষেবা অ্যাকাউন্ট ম্যাপ করা আছে। {recommendationsFeed} অবশ্যই সেই পার্টনারের জন্য Google-এর তৈরি করা ফিড আইডি বা -staging প্রত্যয় সহ ফিড আইডি হতে হবে।

ReplaceCandidatesRequest

JSON অনুরোধের প্রধান অংশের স্ট্রাকচার নিচে দেওয়া হল:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
recommendation_candidates array of RecommendationCandidate হ্যাঁ ১ থেকে ২৫টি RecommendationCandidate আইটেমের তালিকা। এইসব ক্যান্ডিডেট ফিডের বর্তমান ক্যান্ডিডেটকে রিপ্লেস করে।

প্রার্থীর স্কিমা

recommendation_candidates-এর প্রতিটি আইটেম হল একটি RecommendationCandidate অবজেক্ট যার মধ্যে একটি ক্যান্ডিডেট-টাইপ পেলোড, ঐচ্ছিক সাজেশনের কারণ এবং ঐচ্ছিক ডিসপ্লে উপলভ্যতা উইন্ডো থাকে।

RecommendationCandidate

RecommendationCandidate অবজেক্টে ঠিক একটি মিডিয়া-টাইপ পেলোড ফিল্ড, ঐচ্ছিক সাজেশনের কারণ এবং ঐচ্ছিক উপলভ্যতার ইন্টারভাল থাকে।

ইউনিয়ন ফিল্ড candidate_type

candidate_type প্রয়োজন: নিম্নলিখিত ফিল্ডগুলির মধ্যে ঠিক একটি সেট করুন। The fields are mutually exclusive, and a candidate that sets none or more than one is rejected. JSON-এ কোনও candidate_type কী নেই; বেছে নেওয়া ফিল্ডটি সরাসরি RecommendationCandidate অবজেক্টে সেট করুন।

ফিল্ড ধরন বর্ণনা
movie_candidate MovieCandidate চাহিদা অনুযায়ী সিনেমা (MovieCandidate দেখুন)।
tv_show_candidate TvShowCandidate শো লেভেলে টিভি শো (TvShowCandidate দেখুন)।
live_tv_program_candidate LiveTvProgramCandidate শিডিউল করা লাইভ টিভি ব্রডকাস্ট বা স্ট্রিম করা ইভেন্ট (LiveTvProgramCandidate দেখুন)।

প্রসঙ্গ ও উপলভ্যতা

দুটি ফিল্ডই ঐচ্ছিক:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
recommendation_contexts array of RecommendationContext না কেন প্রার্থীকে সাজেস্ট করা হয়েছে এবং প্রতিটি কারণ কতদিন পর্যন্ত প্রযোজ্য (RecommendationContext দেখুন)।
availability_intervals array of Interval না টাইম উইন্ডো যার মধ্যে প্রার্থীকে দেখানো হতে পারে (Interval দেখুন)। প্রতিটি উইন্ডো তার start_time (অন্তর্ভুক্ত) থেকে শুরু হয় এবং তার end_time (এক্সক্লুসিভ) এ শেষ হয়। সেট করা না থাকলে, প্রার্থী যতক্ষণ স্টোর করা থাকে ততক্ষণ উপযুক্ত থাকে। যেসব ক্যান্ডিডেটের উইন্ডো অতীতে রয়েছে তাদের কখনও দেখানো হয় না।

MovieCandidate

MovieCandidate অবজেক্টটি একটি অন-ডিমান্ড মুভিকে উপস্থাপন করে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
title LocalizedString হ্যাঁ সিনেমার নাম (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ১০০ ইউনিকোড কোড পয়েন্ট এবং যেভাবে পাঠানো হয়েছে সেভাবেই দেখানো হয়।
description LocalizedString হ্যাঁ সিনেমার সংক্ষিপ্ত বিবরণ (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ৪০০ ইউনিকোড কোড পয়েন্ট।
localized_media_images array of LocalizedMediaImage হ্যাঁ ১৬:৯ আর্টওয়ার্ক ছবি, ভাষা প্রতি একটি এন্ট্রি (LocalizedMediaImage দেখুন)। অন্তত একটি ছবি থাকতে হবে। উপলভ্য সবচেয়ে বড় সোর্স প্রদান করুন; ১৯২০x১০৮০ পিক্সেল সাজেস্ট করা হয়।
localized_provider_playback_uris array of LocalizedProviderPlaybackUri হ্যাঁ প্রতি প্ল্যাটফর্ম ও প্রতি ভাষা পিছু ডিপ লিঙ্ক (LocalizedProviderPlaybackUri দেখুন)। অন্তত একটি এন্ট্রিতে PLATFORM_ANDROID_TV তালিকাভুক্ত থাকতে হবে।
release_date Date হ্যাঁ সিনেমা রিলিজের তারিখ (Date দেখুন)।
external_entity_ids array of ExternalEntityId না এন্টিটি ম্যাচ করার জন্য এক্সটার্নাল ক্যাটালগ আইডেন্টিফায়ার (ExternalEntityId দেখুন)। প্রতিটি আইডেন্টিফায়ারের ধরনের জন্য সর্বাধিক একটি এন্ট্রি।
duration string (Duration) না সিনেমাটি কতক্ষণ চলবে (Duration দেখুন)। যেমন, ২ ঘণ্টার জন্য "7200s"।
content_ratings array of ContentRating না অফিসিয়াল কন্টেন্ট রেটিং (ContentRating দেখুন)।

TvShowCandidate

TvShowCandidate অবজেক্ট শো লেভেলে টিভি শোকে দেখায়। Google TV এবং Android TV ডিভাইসে শোয়ের জন্য একটি কার্ড দেখানো হয়; প্লেব্যাক শোয়ের পৃষ্ঠায় নাকি নির্দিষ্ট কোনও পর্বে শুরু হবে তা ঠিক করতে ডিপ লিঙ্ক ব্যবহার করুন।

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
title LocalizedString হ্যাঁ টিভি শোয়ের নাম (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ১০০ ইউনিকোড কোড পয়েন্ট এবং যেভাবে পাঠানো হয়েছে সেভাবেই দেখানো হয়।
description LocalizedString হ্যাঁ টিভি শোয়ের সংক্ষিপ্ত বিবরণ (LocalizedString দেখুন)। প্রতিটি ভ্যালু ১ থেকে ৪০০ ইউনিকোড কোড পয়েন্টের মধ্যে হতে হবে।
localized_media_images array of LocalizedMediaImage হ্যাঁ ১৬:৯ আর্টওয়ার্ক ছবি, ভাষা প্রতি একটি এন্ট্রি (LocalizedMediaImage দেখুন)। অন্তত একটি ছবি থাকতে হবে। উপলভ্য সবচেয়ে বড় সোর্স প্রদান করুন; ১৯২০x১০৮০ পিক্সেল সাজেস্ট করা হয়।
localized_provider_playback_uris array of LocalizedProviderPlaybackUri হ্যাঁ প্রতি প্ল্যাটফর্ম ও প্রতি ভাষা পিছু ডিপ লিঙ্ক (LocalizedProviderPlaybackUri দেখুন)। অন্তত একটি এন্ট্রিতে PLATFORM_ANDROID_TV তালিকাভুক্ত থাকতে হবে। uri-এ শো পৃষ্ঠা বা কোনও পর্বের লিঙ্ক থাকতে পারে।
first_episode_air_date Date হ্যাঁ প্রথম এপিসোড সম্প্রচারের তারিখ (Date দেখুন)।
external_entity_ids array of ExternalEntityId না এন্টিটি ম্যাচ করার জন্য এক্সটার্নাল ক্যাটালগ আইডেন্টিফায়ার (ExternalEntityId দেখুন)। প্রতিটি আইডেন্টিফায়ারের ধরনের জন্য সর্বাধিক একটি এন্ট্রি।
season_count integer (int32) না আপনার পরিষেবায় উপলভ্য সিজনের সংখ্যা।
content_ratings array of ContentRating না অফিসিয়াল কন্টেন্ট রেটিং (ContentRating দেখুন)।

LiveTvProgramCandidate

LiveTvProgramCandidate অবজেক্ট শিডিউল করা লাইভ টিভি ব্রডকাস্ট বা স্ট্রিম করা ইভেন্টকে দেখায়। ব্রডকাস্ট উইন্ডো হল প্রার্থীর অংশ এবং এটি পেরেন্ট প্রার্থীর availability_intervals থেকে আলাদা, যা কার্ড কখন দেখানো হতে পারে তা নিয়ন্ত্রণ করে।

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
title LocalizedString হ্যাঁ লাইভ টিভি প্রোগ্রামের নাম (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ১০০ ইউনিকোড কোড পয়েন্ট এবং যেভাবে পাঠানো হয়েছে সেভাবেই দেখানো হয়।
description LocalizedString হ্যাঁ লাইভ টিভি প্রোগ্রামের সংক্ষিপ্ত বিবরণ (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ৪০০ ইউনিকোড কোড পয়েন্ট।
localized_media_images array of LocalizedMediaImage হ্যাঁ ১৬:৯ আর্টওয়ার্ক ছবি, ভাষা প্রতি একটি এন্ট্রি (LocalizedMediaImage দেখুন)। অন্তত একটি ছবি থাকতে হবে। উপলভ্য সবচেয়ে বড় সোর্স প্রদান করুন; ১৯২০x১০৮০ পিক্সেল সাজেস্ট করা হয়।
localized_provider_playback_uris array of LocalizedProviderPlaybackUri হ্যাঁ প্রতি প্ল্যাটফর্ম ও প্রতি ভাষা পিছু ডিপ লিঙ্ক (LocalizedProviderPlaybackUri দেখুন)। অন্তত একটি এন্ট্রিতে PLATFORM_ANDROID_TV তালিকাভুক্ত থাকতে হবে।
broadcast_interval Interval হ্যাঁ প্রোগ্রামের ব্রডকাস্ট শুরু ও শেষ হওয়ার সময় (Interval দেখুন)। start_time ও end_time দুটিই প্রয়োজন।
external_entity_ids array of ExternalEntityId না এন্টিটি ম্যাচ করার জন্য এক্সটার্নাল ক্যাটালগ আইডেন্টিফায়ার (ExternalEntityId দেখুন)। প্রতিটি আইডেন্টিফায়ারের ধরনের জন্য সর্বাধিক একটি এন্ট্রি।
content_ratings array of ContentRating না অফিসিয়াল কন্টেন্ট রেটিং (ContentRating দেখুন)।

সহায়ক স্কিমা

ক্যান্ডিডেট পেলোড, লোকালাইজড টেক্সট, ডিপ লিঙ্ক, আর্টওয়ার্ক, এক্সটার্নাল আইডেন্টিফায়ার, সাজেস্ট করার কারণ, ডিসপ্লে ইন্টারভাল, কন্টেন্ট রেটিং এবং সুপরিচিত তারিখ ও সময়ের ধরন সংক্রান্ত নিম্নলিখিত শেয়ার করা অবজেক্ট রেফারেন্স করে।

LocalizedString

LocalizedString অবজেক্টে এক বা একাধিক ভাষায় একই টেক্সট থাকে। প্রতিটি ভ্যালু তার ভাষার সাথে ট্যাগ করা থাকে যাতে Google TV এবং Android TV ডিভাইস ব্যবহারকারীর টিভি ডিভাইসের ভাষার সাথে মেলে এমন টেক্সট দেখাতে পারে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
values array of LocalizedText হ্যাঁ আপনার প্রদান করা প্রতিটি ভাষার টেক্সট (LocalizedText দেখুন)। কমপক্ষে একটি ভ্যালু থাকতে হবে।

LocalizedText

LocalizedText অবজেক্টটি একটি ভাষায় লেখা টেক্সট:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
text string হ্যাঁ language_code-এর দেওয়া ভাষায় টেক্সট।
language_code string হ্যাঁ text-এর BCP-47 ভাষা কোড, যেমন "en-US" বা "sr-Latn"।

LocalizedMediaImage

LocalizedMediaImage অবজেক্টটি কোনও ছবির সাথে সেই ছবিতে থাকা যেকোনও টেক্সটের ভাষাকে পেয়ার করে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
language_code string হ্যাঁ ছবির টেক্সটের BCP-47 ভাষা কোড, যেমন "en-US" বা "sr-Latn"।
image MediaImage হ্যাঁ ১৬:৯ অনুপাতের ছবি (MediaImage দেখুন)। উপলভ্য সবচেয়ে বড় সোর্স প্রদান করুন; ১৯২০x১০৮০ পিক্সেল হলে ভালো হয়।

LocalizedProviderPlaybackUri

LocalizedProviderPlaybackUri অবজেক্ট, ডিপ লিঙ্কের সাথে কন্টেন্টের ভাষা ও যে অ্যাপে এটি খোলা হয় সেটিকে পেয়ার করে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
playback_uri PlaybackUri হ্যাঁ ডিপ লিঙ্ক এবং এটি যেসব প্ল্যাটফর্মে প্রযোজ্য (PlaybackUri দেখুন)।
language_code string হ্যাঁ ডিপ লিঙ্ক যে কন্টেন্ট খোলে সেটির BCP-47 ভাষা কোড, যেমন "en-US" বা "sr-Latn"।
package_name string হ্যাঁ ডিপ লিঙ্ক খুলতে Android অ্যাপ্লিকেশন প্যাকেজের নাম ব্যবহার করা হয় (যেমন, "com.example.tvapp")।

PlaybackUri

PlaybackUri অবজেক্ট ডিপ লিঙ্ক ও তার টার্গেট প্ল্যাটফর্মকে সংজ্ঞায়িত করে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
uri string হ্যাঁ ডিপ লিঙ্ক URI যা আপনার অ্যাপে ক্যান্ডিডেটের প্লেব্যাক শুরু করে।
platforms array of string (enum) হ্যাঁ এই ডিপ লিঙ্ক যেসব প্ল্যাটফর্মে প্রযোজ্য। অনুমোদিত ভ্যালু: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Google TV ও Android TV ডিভাইসের জন্য PLATFORM_ANDROID_TV অন্তর্ভুক্ত করুন।

MediaImage

MediaImage অবজেক্ট ছবির URL, পিক্সেল ডাইমেনশন ও অ্যাক্সেসিবিলিটি টেক্সট নির্দিষ্ট করে:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
url string হ্যাঁ ছবির সর্বজনীনভাবে অ্যাক্সেসযোগ্য HTTPS URL।
width integer হ্যাঁ পিক্সেলে ছবির অপরিবর্তিত (সর্বাধিক) প্রস্থ।
height integer হ্যাঁ পিক্সেলে ছবির অপরিবর্তিত (সর্বাধিক) উচ্চতা।
accessibility_text string হ্যাঁ ছবির বর্ণনা সহ অ্যাক্সেসিবিলিটি (অল্টারনেট) টেক্সট।

ExternalEntityId

ExternalEntityId অবজেক্ট, এক্সটার্নাল ক্যাটালগে কোনও ক্যান্ডিডেটকে শনাক্তকারীর সাথে ম্যাপ করে। প্রতিটি এন্ট্রির জন্য নিম্নলিখিত ফিল্ডগুলির মধ্যে ঠিক একটি সেট করুন এবং প্রার্থীর external_entity_ids তালিকায় শনাক্তকারীর ধরন প্রতি সর্বাধিক একটি এন্ট্রি অন্তর্ভুক্ত করুন:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
tms_root_id string এর মধ্যে একটি Gracenote TMS রুট আইডি। একটি শীর্ষক শনাক্ত করে: একটি সিনেমা, একটি শো বা একটি পর্ব।
tms_id string এর মধ্যে একটি Gracenote TMS ভেরিয়েন্ট আইডি। কোনও সংস্করণ বা ব্রডকাস্ট তালিকা শনাক্ত করে।
data_feed_element_id string এর মধ্যে একটি আপনার মিডিয়া অ্যাকশন ডেটা ফিড থেকে এন্টিটি আইডি। এই ভ্যালু রিসোর্স নামের {recommendationsFeed} সেগমেন্টের সাথে সম্পর্কিত নয়।

RecommendationContext

RecommendationContext অবজেক্ট ব্যাখ্যা করে যে কেন একজন প্রার্থীকে সাজেস্ট করা হয়েছে এবং কতক্ষণ সেই ব্যাখ্যা প্রযোজ্য:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
recommendation_reason RecommendationReason না কেন প্রার্থীকে সাজেস্ট করা হয়েছে (RecommendationReason দেখুন)।
validity_interval Interval না টাইম উইন্ডো যার মধ্যে এই প্রসঙ্গ প্রযোজ্য (Interval দেখুন)। যেমন, একজন প্রার্থী শুধুমাত্র সীমিত সংখ্যক দিনের জন্য নতুন। সেট না করা থাকলে, ক্যান্ডিডেট যত দিন স্টোর করা থাকবে তত দিন পর্যন্ত প্রসঙ্গ প্রযোজ্য হবে।

RecommendationReason

RecommendationReason অবজেক্টে একটি কারণ থাকে। নিম্নলিখিত ফিল্ডগুলির মধ্যে ঠিক একটি সেট করুন:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
top_on_partner object এর মধ্যে একটি প্রার্থী আপনার পরিষেবার একটি র‍্যাঙ্ক করা শীর্ষ আইটেম। এতে একটি পজিটিভ ইন্টিজার ফিল্ড rank থাকে (যেমন, "পার্টনারের মধ্যে সেরা ১"-এর জন্য {"rank": 1})।
popular_on_partner object এর মধ্যে একটি আপনার পরিষেবায় প্রার্থী জনপ্রিয়। একটি খালি অবজেক্ট ({}) পাস করুন।
new_on_partner object এর মধ্যে একটি প্রার্থী আপনার পরিষেবায় নতুন। একটি খালি অবজেক্ট ({}) পাস করুন।
generic object এর মধ্যে একটি একটি কাস্টম কারণ। এতে একটি LocalizedString ফিল্ড generic_reason আছে (LocalizedString দেখুন)। প্রতিটি ভ্যালু হল ১ থেকে ১০০ ইউনিকোড কোড পয়েন্ট।

ContentRating

ContentRating অবজেক্টটি কোনও রেটিং এজেন্সির দ্বারা অ্যাসাইন করা অফিসিয়াল কন্টেন্ট রেটিংকে দেখায়:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
rating_system string হ্যাঁ রেটিং এজেন্সি বা সিস্টেম, যেমন "MPAA", "BBFC" বা "CBFC"।
rating_value string হ্যাঁ rating_system-এর দ্বারা নির্ধারিত রেটিং, যেমন "PG-13" বা "U/A 13+"।

Timestamp

Timestamp-কে JSON-এ Z সাফিক্স সহ UTC-তে RFC 3339 স্ট্রিং হিসেবে এনকোড করা হয়, যেমন "2026-10-01T18:00:00Z"। সেকেন্ডের ভগ্নাংশ ব্যবহার করা যাবে, যেমন "2026-10-01T18:00:00.500Z"।

Duration

Duration JSON-এ স্ট্রিং হিসেবে এনকোড করা হয়, যাতে সেকেন্ডের সংখ্যা থাকে এবং এর পরে s প্রত্যয় থাকে, যেমন ২ ঘণ্টার জন্য "7200s"। সেকেন্ডের ভগ্নাংশ ব্যবহার করা যাবে, যেমন "5400.5s"।

Date

Date হল টাইম জোন ছাড়া ক্যালেন্ডারের তারিখ। এটি JSON-এ নিম্নলিখিত ফিল্ড সহ অবজেক্ট হিসেবে এনকোড করা হয়:

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
year integer হ্যাঁ তারিখের বছর, যেমন 2025।
month integer না বছরের মাস, 1 থেকে 12 পর্যন্ত। 0-এ সেট করুন অথবা মাস জানা না থাকলে বাদ দিন।
day integer না 1 থেকে 31 পর্যন্ত মাসের দিন এবং প্রদত্ত বছর ও মাসের জন্য বৈধ। 0-এ সেট করুন অথবা দিনটি জানা না থাকলে বাদ দিন। month আবশ্যক।

যেমন, {"year": 2025, "month": 1, "day": 17} বলতে ১৭ জানুয়ারি, ২০২৫ বোঝায়, {"year": 2025, "month": 1} বলতে ২০২৫ সালের জানুয়ারি মাসের কোনও একটি দিন বোঝায়, এবং {"year": 2025} বলতে ২০২৫ সালের কোনও একটি মাসের কোনও একটি দিন বোঝায়।

Interval

Interval হল একটি হাফ-ওপেন টাইম উইন্ডো যা start_time (অন্তর্ভুক্ত) থেকে শুরু হয় এবং end_time (এক্সক্লুসিভ) এ শেষ হয়। start_time <= T এবং T < end_time হলে, T সময়টি ইন্টারভ্যালের মধ্যে পড়ে।

ফিল্ড ধরন প্রয়োজনীয় বর্ণনা
start_time string (Timestamp) হ্যাঁ উইন্ডোর ইনক্লুসিভ স্টার্ট (Timestamp দেখুন), যেমন "2026-10-01T18:00:00Z"।
end_time string (Timestamp) হ্যাঁ উইন্ডোর এক্সক্লুসিভ শেষ (Timestamp দেখুন), যেমন "2026-10-01T21:00:00Z"। অবশ্যই start_time-এর পরে হতে হবে।

অনুরোধের উদাহরণ

নিম্নলিখিত উদাহরণে পার্টনার example-partner-এর ফিড in-en-cricket-এর ক্যান্ডিডেটকে তিনটি ক্যান্ডিডেট (একটি সিনেমা, একটি টিভি শো এবং একটি লাইভ টিভি প্রোগ্রাম) দিয়ে পরিবর্তন করা হয়েছে। মুভিতে দুটি ভাষায় টেক্সট দেখানো হয়:

curl -X POST \
  "https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "recommendation_candidates": [
      {
        "movie_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Action Movie",
                "language_code": "en-US"
              },
              {
                "text": "Película de acción de ejemplo",
                "language_code": "es-419"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example action movie synopsis.",
                "language_code": "en-US"
              },
              {
                "text": "Sinopsis de una película de acción de ejemplo.",
                "language_code": "es-419"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Action Movie"
              }
            },
            {
              "language_code": "es-419",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Imagen de Película de acción de ejemplo"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=en",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            },
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=es",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "es-419",
              "package_name": "com.example.tvapp"
            }
          ],
          "release_date": {
            "year": 2025,
            "month": 11,
            "day": 14
          },
          "external_entity_ids": [
            {
              "tms_root_id": "MV001234560000"
            }
          ],
          "duration": "7200s",
          "content_ratings": [
            {
              "rating_system": "MPAA",
              "rating_value": "PG-13"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "top_on_partner": {
                "rank": 1
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "tv_show_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Drama Series",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example drama series synopsis.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/show-2002-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Drama Series"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/show-2002",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "first_episode_air_date": {
            "year": 2024,
            "month": 3,
            "day": 8
          },
          "external_entity_ids": [
            {
              "data_feed_element_id": "show-2002"
            }
          ],
          "season_count": 3,
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-14"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "new_on_partner": {}
            },
            "validity_interval": {
              "start_time": "2026-11-01T00:00:00Z",
              "end_time": "2026-11-15T00:00:00Z"
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "live_tv_program_candidate": {
          "title": {
            "values": [
              {
                "text": "Championship Live Broadcast",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "Live coverage of the championship match.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/live-prog-500-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Championship Live Broadcast"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/live/sports-1",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "broadcast_interval": {
            "start_time": "2026-11-15T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          },
          "external_entity_ids": [
            {
              "tms_id": "EP012345670001"
            }
          ],
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-PG"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "generic": {
                "generic_reason": {
                  "values": [
                    {
                      "text": "Live this weekend",
                      "language_code": "en-US"
                    }
                  ]
                }
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-14T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          }
        ]
      }
    ]
  }'

প্রতিক্রিয়া ও প্রতিস্থাপন সংক্রান্ত আচরণ

এই বিভাগে replaceCandidates-এর মাধ্যমে পাঠানো HTTP রেসপন্স এবং প্রতিটি কল কীভাবে আপনার সেভ করা ক্যান্ডিডেট আপডেট করে তা বর্ণনা করা হয়েছে।

ReplaceCandidatesResponse

অনুরোধ সফল হলে, API HTTP 200 OK সহ ReplaceCandidatesResponse বডি রিটার্ন করে:

ফিল্ড ধরন বর্ণনা
replaced_candidates_count integer (int32) কতজন প্রার্থীকে বদল করা হয়েছে।

আগের অনুরোধের উদাহরণ-এর জন্য, উত্তর হল:

{
  "replaced_candidates_count": 3
}

রিপ্লেসমেন্ট সংক্রান্ত আচরণ

আপনার ইন্টিগ্রেশন ডিজাইন করার জন্য replaceCandidates কীভাবে সেভ করা প্রার্থীদের আপডেট করে তা বোঝা প্রয়োজন:

  • ফিড প্রতি সম্পূর্ণ পরিবর্তন। প্রতিটি কল URL পাথে নাম উল্লেখ করা ফিডের জন্য আগে থেকে সেভ করা ক্যান্ডিডেট তালিকা সম্পূর্ণভাবে প্রতিস্থাপন করে। সেই ফিডের জন্য সবসময় অ্যাক্টিভ ক্যান্ডিডেটের সম্পূর্ণ সেট পাঠান।
  • অন্যান্য ফিড অপরিবর্তিত থাকবে। আপনি যেসব ফিডে ক্যান্ডিডেট পাঠান না, সেগুলি আপনি না পাঠানো পর্যন্ত অপরিবর্তিত থাকে। যেমন, একটি ফিডের ক্যান্ডিডেট পরিবর্তন করলে, অন্য কোনও ফিডের জন্য আপনার সেভ করা ক্যান্ডিডেট পরিবর্তন হয় না এবং {recommendationsFeed}-staging-এর ক্যান্ডিডেট পরিবর্তন করলে, {recommendationsFeed} পরিবর্তন হয় না।
  • প্রতি ফিডে একটি কল। একাধিক ফিড আপডেট করতে, প্রতিটি ফিডের জন্য একটি করে কল করুন। কলগুলি একে অপরের থেকে স্বাধীন: একটি কল ব্যর্থ হলে, অন্য ফিডগুলি তাদের নতুন প্রার্থী রাখে এবং আপনি শুধুমাত্র ব্যর্থ কলটি আবার চেষ্টা করেন।
  • কমপক্ষে প্রতি ৩০ দিন অন্তর অ্যাক্টিভ ফিড আবার পাঠান। কোনও ফিডের জন্য আপনার ক্যাটালগ পরিবর্তিত না হলেও, প্রতি ৩০ দিনে অন্তত একবার প্রতিটি অ্যাক্টিভ ফিড আবার পাঠান (অথবা র‍্যান্ডমাইজড জিটার সহ নিয়মিত দৈনিক বা সাপ্তাহিক শিডিউলে) যাতে আপনার ক্যান্ডিডেট অ্যাক্টিভ থাকে এবং মেয়াদ শেষ না হয়ে যায়। availability_intervals end_time অনেক পরে সেট করলে তা পর্যায়ক্রমিক রিসেন্ডিংকে প্রতিস্থাপন করে না।
  • অ্যাটমিক এক্সিকিউশন। API অনুরোধটি অ্যাটমিক্যালি প্রয়োগ করে। কোনও ক্যান্ডিডেট যাচাইকরণে ব্যর্থ হলে, API সম্পূর্ণ অনুরোধ বাতিল করে দেয় এবং ফিড তার আগের ক্যান্ডিডেটদের রেখে দেয়।