অ্যাড-অন অ্যাকশন

অ্যাড-অন অ্যাকশন উইজেটগুলিতে ইন্টারেক্টিভ আচরণ প্রদান করে। একটি অ্যাকশন তৈরি করার মাধ্যমে, ব্যবহারকারী যখন কোনো উইজেট নির্বাচন বা আপডেট করে, তখন কী ঘটবে তা আপনি নির্ধারণ করেন।

বেশিরভাগ ক্ষেত্রে, আপনি গুগল অ্যাপস স্ক্রিপ্ট কার্ড পরিষেবা দ্বারা প্রদত্ত Action অবজেক্ট ব্যবহার করে অ্যাড-অন অ্যাকশন সংজ্ঞায়িত করতে পারেন। প্রতিটি Action তৈরি করার সময় এর সাথে একটি কলব্যাক ফাংশন যুক্ত থাকে। ব্যবহারকারী যখন উইজেটটির সাথে ইন্টারঅ্যাক্ট করে, তখন নির্বাচিত পদক্ষেপগুলো নেওয়ার জন্য আপনাকে কলব্যাক ফাংশনটি ইমপ্লিমেন্ট করতে হয়। এছাড়াও, আপনাকে অবশ্যই একটি উপযুক্ত উইজেট হ্যান্ডলার ফাংশন ব্যবহার করে Action উইজেটের সাথে লিঙ্ক করতে হবে, যা নির্ধারণ করে কোন ধরনের ইন্টারঅ্যাকশন Action কলব্যাকটিকে ট্রিগার করবে।

এই প্রক্রিয়া ব্যবহার করে একটি উইজেটকে Action সহ কনফিগার করুন:

1. Action অবজেক্টটি তৈরি করুন এবং এর সাথে প্রয়োজনীয় প্যারামিটারগুলোসহ যে কলব্যাক ফাংশনটি এটি সম্পাদন করবে তা উল্লেখ করুন।
2. Action অবজেক্ট ব্যবহার করে উইজেটটিতে উপযুক্ত উইজেট হ্যান্ডলার ফাংশনটি কল করুন।
3. প্রয়োজনীয় আচরণ কার্যকর করার জন্য কলব্যাক ফাংশনটি প্রয়োগ করুন।

Action অবজেক্ট এবং CardAction অবজেক্টকে গুলিয়ে ফেলবেন না। CardAction অবজেক্ট হলো কার্ড হেডার মেনু আইটেম, অন্যদিকে Action অবজেক্ট UI-এর সাথে ব্যবহারকারীর মিথস্ক্রিয়ার প্রতিক্রিয়া নির্ধারণ করে।

উইজেট হ্যান্ডলার ফাংশন

কোনো উইজেটকে একটি Action বা অন্য কোনো আচরণের সাথে সংযুক্ত করতে, একটি উইজেট হ্যান্ডলার ফাংশন ব্যবহার করুন। হ্যান্ডলার ফাংশনটি নির্ধারণ করে যে কোন ধরনের ইন্টারঅ্যাকশন (উদাহরণস্বরূপ, উইজেটে ক্লিক করা বা একটি টেক্সট ফিল্ড সম্পাদনা করা) অ্যাকশন আচরণটিকে ট্রিগার করবে। হ্যান্ডলার ফাংশনটি আরও নির্ধারণ করে যে অ্যাকশনটি সম্পন্ন হওয়ার পরে UI কী কী পদক্ষেপ নেবে, যদি কোনো পদক্ষেপ নেওয়ার প্রয়োজন হয়।

নিম্নলিখিত সারণিতে উইজেটগুলির বিভিন্ন হ্যান্ডলারের প্রকার এবং সেগুলি কোন কোন উইজেটের সাথে ব্যবহৃত হয় তা তালিকাভুক্ত করা হলো:

হ্যান্ডলার ফাংশন	ক্রিয়া শুরু করে	প্রযোজ্য উইজেট	বর্ণনা
setOnChangeAction	উইজেটের মান পরিবর্তন হয়	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	এমন একটি Action সেট করে যা উইজেটটি ফোকাস হারালে (যেমন, ব্যবহারকারী কোনো ইনপুটে টেক্সট লিখে এন্টার চাপলে) একটি অ্যাপস স্ক্রিপ্ট ফাংশন এক্সিকিউট করে। হ্যান্ডলারটি স্বয়ংক্রিয়ভাবে তার কল করা ফাংশনে একটি ইভেন্ট অবজেক্ট পাঠিয়ে দেয়। নির্বাচিত হলে, আপনি এই ইভেন্ট অবজেক্টে অতিরিক্ত প্যারামিটার তথ্য যোগ করতে পারেন।
setOnClickAction	ব্যবহারকারী উইজেটটিতে ক্লিক করেন।	CardAction Image ImageButton DecoratedText TextButton	ব্যবহারকারী উইজেটটিতে ক্লিক করলে একটি অ্যাপস স্ক্রিপ্ট ফাংশন কার্যকর করার জন্য একটি Action সেট করে। হ্যান্ডলারটি স্বয়ংক্রিয়ভাবে তার কল করা ফাংশনে একটি ইভেন্ট অবজেক্ট পাঠিয়ে দেয়। আপনি এই ইভেন্ট অবজেক্টে ঐচ্ছিক প্যারামিটার তথ্য যোগ করতে পারেন।
setComposeAction	ব্যবহারকারী উইজেটটিতে ক্লিক করেন।	CardAction Image ImageButton DecoratedText TextButton	জিমেইল-এর জন্য নির্দিষ্ট। এটি এমন একটি Action সেট করে যা একটি ইমেল ড্রাফট তৈরি করে এবং তারপর সেই ড্রাফটটি জিমেইল UI-এর একটি কম্পোজ উইন্ডোতে ব্যবহারকারীর সামনে উপস্থাপন করে। আপনি ড্রাফটটি একটি নতুন মেসেজ হিসেবে অথবা জিমেইলে খোলা কোনো মেসেজের রিপ্লাই হিসেবে তৈরি করতে পারেন। যখন হ্যান্ডলারটি ড্রাফট-বিল্ডিং কলব্যাক ফাংশনটি কল করে, তখন এটি কলব্যাক ফাংশনটিতে একটি ইভেন্ট অবজেক্ট পাস করে। আরও বিস্তারিত জানতে ‘কম্পোজ ড্রাফট মেসেজ’ দেখুন।
setOnClickOpenLinkAction	ব্যবহারকারী উইজেটটিতে ক্লিক করেন।	CardAction Image ImageButton DecoratedText TextButton	ব্যবহারকারী উইজেটে ক্লিক করলে একটি URL খোলার জন্য একটি Action সেট করে। যখন আপনাকে অবশ্যই URL তৈরি করতে হবে অথবা লিঙ্কটি খোলার আগে অন্য কোনো কাজ সম্পন্ন করতে হবে, তখন এই হ্যান্ডলারটি ব্যবহার করুন; অন্যথায় সাধারণত setOpenLink ব্যবহার করা সহজতর হয়। আপনি শুধুমাত্র একটি নতুন উইন্ডোতে URL-টি খুলতে পারবেন। বন্ধ করার সময়, আপনি UI-কে অ্যাড-অনটি রিলোড করাতে পারেন।
setOpenLink	ব্যবহারকারী উইজেটটিতে ক্লিক করেন।	CardAction Image ImageButton DecoratedText TextButton	ব্যবহারকারী উইজেটটিতে ক্লিক করলে সরাসরি একটি ইউআরএল খোলে। যখন আপনি ইউআরএলটি জানেন এবং শুধু সেটি খোলার প্রয়োজন হয়, তখন এই হ্যান্ডলারটি ব্যবহার করুন; অন্যথায় setOnClickOpenLinkAction ব্যবহার করুন। আপনি ইউআরএলটি একটি নতুন উইন্ডোতে বা একটি ওভারলেতে খুলতে পারেন। বন্ধ করার সময়, আপনি অ্যাড-অনটি UI-তে রিলোড করাতে পারেন।
setSuggestionsAction	ব্যবহারকারী একটি ইনপুটে টেক্সট প্রবেশ করান।	TextInput	যখন ব্যবহারকারী কোনো টেক্সট ইনপুট উইজেটে টেক্সট প্রবেশ করান, তখন এই Action একটি অ্যাপস স্ক্রিপ্ট ফাংশন কার্যকর করে। হ্যান্ডলারটি স্বয়ংক্রিয়ভাবে তার কল করা ফাংশনে একটি ইভেন্ট অবজেক্ট পাঠিয়ে দেয়। আরও বিস্তারিত জানতে টেক্সট ইনপুটের জন্য অটোকমপ্লিট সাজেশন দেখুন।

কলব্যাক ফাংশন

যখন কোনো Action ট্রিগার হয়, তখন কলব্যাক ফাংশনগুলো কার্যকর হয়। যেহেতু কলব্যাক ফাংশনগুলো অ্যাপস স্ক্রিপ্ট ফাংশন, তাই অন্য যেকোনো স্ক্রিপ্ট ফাংশন যা যা করতে পারে, তার প্রায় সবকিছুই আপনি এগুলোর মাধ্যমে করাতে পারেন।

সতর্কীকরণ: অ্যাপস স্ক্রিপ্ট কার্ড সার্ভিস কলব্যাক ফাংশনগুলোর এক্সিকিউশন টাইম সর্বোচ্চ ৩০ সেকেন্ডে সীমাবদ্ধ করে। যদি এক্সিকিউশন এর চেয়ে বেশি সময় নেয়, তাহলে Action প্রতিক্রিয়ায় আপনার অ্যাড-অন UI তার কার্ড ডিসপ্লে সঠিকভাবে আপডেট নাও করতে পারে।

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

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

পদক্ষেপের চেষ্টা করা হয়েছিল	কলব্যাক ফাংশন ফেরত দেওয়া উচিত
নেভিগেট করুন	ActionResponse
একটি Notification প্রদর্শন করুন	ActionResponse
setOnClickOpenLinkAction ব্যবহার করে একটি লিঙ্ক খুলুন	ActionResponse
অটোকমপ্লিট সাজেশন প্রদর্শন করুন	SuggestionResponse
একটি সার্বজনীন ক্রিয়া ব্যবহার করুন	UniversalActionResponse
অন্যান্য পদক্ষেপ	কিছুই না

গুগল ওয়ার্কস্পেস হোস্ট অ্যাপ্লিকেশনগুলির জন্য পদক্ষেপ

এই কাজগুলো ছাড়াও, প্রতিটি হোস্ট অ্যাপ্লিকেশনের নিজস্ব কিছু কাজ থাকে যা শুধুমাত্র সেই হোস্টেই করা যায়। বিস্তারিত জানতে, নিম্নলিখিত নির্দেশিকাগুলো দেখুন:

• ক্যালেন্ডারের কার্যকলাপ
• চ্যাট কার্যক্রম
• পদক্ষেপ চালনা করুন
• জিমেইল কার্যক্রম
• সম্পাদকের কার্যকলাপ

রেসপন্স বিল্ডার ক্লাস ব্যবহার করার সময়, রেসপন্স অবজেক্টগুলো তৈরি করতে build মেথডটি কল করুন। তা করতে ব্যর্থ হলে একটি এরর দেখা দেবে।

ইউনিভার্সাল অ্যাকশনগুলো প্রজেক্ট ম্যানিফেস্টে সংজ্ঞায়িত করা থাকে এবং এগুলোর জন্য Action অবজেক্টের প্রয়োজন হয় না, কিন্তু এদের কলব্যাক ফাংশনগুলোকে অবশ্যই একটি UniversalActionResponse রিটার্ন করতে হবে।

অ্যাকশন ইভেন্ট অবজেক্ট

যখন আপনার অ্যাড-অন কোনো Action ট্রিগার করে, তখন UI স্বয়ংক্রিয়ভাবে একটি JSON ইভেন্ট অবজেক্ট তৈরি করে এবং সেটিকে Action কলব্যাক ফাংশনে একটি আর্গুমেন্ট হিসেবে পাস করে। এই ইভেন্ট অবজেক্টটিতে ব্যবহারকারীর বর্তমান ক্লায়েন্ট-সাইড কনটেক্সট সম্পর্কিত তথ্য থাকে, যেমন প্রদর্শিত কার্ডের সমস্ত ইন্টারেক্টিভ উইজেটের বর্তমান মান।

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

ইভেন্ট অবজেক্টের গঠন সম্পর্কে বিস্তারিত জানতে ইভেন্ট অবজেক্টসমূহ দেখুন।

জিমেইল অ্যাড-অনগুলো এই ইভেন্ট অবজেক্ট কাঠামোর একটি সরলীকৃত সংস্করণ ব্যবহার করত, যা এখন অপ্রচলিত। পূর্ববর্তী সংস্করণের সাথে সামঞ্জস্য রাখার জন্য, মূল জিমেইল অ্যাড-অনগুলোর সমস্ত ইভেন্ট অবজেক্ট ফিল্ড এখনও নতুন ইভেন্ট অবজেক্ট কাঠামোর মধ্যে অন্তর্ভুক্ত রয়েছে ( ইভেন্ট অবজেক্ট কাঠামো দেখুন)। তবে, একই তথ্য commonEventObject এবং Gmail ইভেন্ট অবজেক্ট উপ-কাঠামোতে পুনরুৎপাদিত হয়েছে। আপনি যদি একটি জিমেইল অ্যাড-অনকে গুগল ওয়ার্কস্পেস অ্যাড-অনে আপগ্রেড করেন, তবে আপডেট করা ইভেন্ট অবজেক্ট ফিল্ডগুলো ব্যবহার করার জন্য আপনার কোডটি পরিবর্তন করুন। অবশেষে, মূল জিমেইল ইভেন্ট অবজেক্ট ফিল্ডগুলো সরিয়ে ফেলা হবে।