সর্বজনীন কর্ম

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

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

• একটি সেটিংস ওয়েব পৃষ্ঠা খুলুন (বা একটি সেটিংস কার্ড প্রদর্শন করুন)।
• ব্যবহারকারীকে সাহায্যের তথ্য দেখান।
• একটি নতুন কর্মপ্রবাহ শুরু করুন, যেমন 'নতুন গ্রাহক যোগ করুন'।
• একটি কার্ড প্রদর্শন করুন যা একজন ব্যবহারকারীকে অ্যাড-অন সম্পর্কে প্রতিক্রিয়া পাঠাতে দেয়।

যখনই আপনার কাছে এমন একটি কর্ম থাকে যা বর্তমান প্রেক্ষাপটের উপর নির্ভর করে না, তখন আপনার এটিকে একটি সর্বজনীন কর্ম হিসাবে বিবেচনা করা উচিত।

সার্বজনীন কর্ম ব্যবহার করে

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

সার্বজনীন কর্ম কনফিগার করা

আপনি আপনার অ্যাড-অনের ম্যানিফেস্টে সর্বজনীন ক্রিয়াগুলি কনফিগার করেন; আরো বিস্তারিত জানার জন্য ম্যানিফেস্ট দেখুন।

প্রতিটি কর্মের জন্য, আপনি সেই কর্মের জন্য মেনুতে প্রদর্শিত পাঠ্যটি নির্দিষ্ট করুন৷ তারপরে আপনি একটি openLink ক্ষেত্র নির্দিষ্ট করতে পারেন যা নির্দেশ করে যে কর্মটি সরাসরি একটি নতুন ট্যাবে একটি ওয়েব পৃষ্ঠা খুলতে হবে। বিকল্পভাবে, আপনি একটি runFunction ক্ষেত্র নির্দিষ্ট করতে পারেন যা সার্বজনীন ক্রিয়া নির্বাচন করা হলে চালানোর জন্য একটি Apps স্ক্রিপ্ট কলব্যাক ফাংশন নির্দিষ্ট করে৷

যখন runFunction ব্যবহার করা হয়, নির্দিষ্ট কলব্যাক ফাংশন সাধারণত নিম্নলিখিতগুলির মধ্যে একটি করে:

• একটি নির্মিত UniversalActionResponse অবজেক্ট ফিরিয়ে দিয়ে অবিলম্বে প্রদর্শনের জন্য UI কার্ড তৈরি করে।
• একটি ইউআরএল খোলে, সম্ভবত অন্যান্য কাজ করার পরে, একটি নির্মিত UniversalActionResponse অবজেক্ট ফিরিয়ে দিয়ে।
• ব্যাকগ্রাউন্ডের কাজগুলি পরিচালনা করে যা একটি নতুন কার্ডে স্যুইচ করে না বা একটি URL খোলে না। এই ক্ষেত্রে কলব্যাক ফাংশন কিছুই প্রদান করে না।

কল করা হলে, কলব্যাক ফাংশনটি খোলা কার্ড এবং অ্যাড-অন প্রসঙ্গের তথ্য সম্বলিত একটি ইভেন্ট অবজেক্ট পাস করে।

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

উদাহরণ

নিম্নলিখিত কোড স্নিপেটে Google Workspace অ্যাড-অনের একটি উদাহরণ ম্যানিফেস্ট উদ্ধৃতি দেখায় যা Gmail প্রসারিত করার সময় সর্বজনীন অ্যাকশন ব্যবহার করে। কোডটি স্পষ্টভাবে একটি মেটাডেটা স্কোপ সেট করে যাতে অ্যাড-অন নির্ধারণ করতে পারে কে খোলা বার্তা পাঠিয়েছে।

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

পূর্ববর্তী উদাহরণে সংজ্ঞায়িত তিনটি সর্বজনীন ক্রিয়া নিম্নলিখিতগুলি করে:

• ওপেন google.com একটি নতুন ট্যাবে https://www.google.com খোলে।
• ওপেন কন্টাক্ট ইউআরএল একটি ফাংশন চালায় যা কোন ইউআরএল খুলতে হবে তা নির্ধারণ করে এবং তারপর একটি OpenLink অবজেক্ট ব্যবহার করে একটি নতুন ট্যাবে খোলে। কোডটি প্রেরকের ইমেল ঠিকানা ব্যবহার করে URL তৈরি করে।
• ওপেন সেটিংস অ্যাড-অন স্ক্রিপ্ট প্রকল্পে সংজ্ঞায়িত createSettingsCards() ফাংশন চালায়। এই ফাংশনটি একটি বৈধ UniversalActionResponse অবজেক্ট প্রদান করে যাতে অ্যাড-অন সেটিং এবং অন্যান্য তথ্য সহ কার্ডের একটি সেট থাকে। ফাংশনটি এই অবজেক্টটি তৈরি করার পরে, UI কার্ডের তালিকা প্রদর্শন করে ( একাধিক কার্ড ফেরানো দেখুন)।
• রান ব্যাকগ্রাউন্ড সিঙ্ক রান runBackgroundSync() ফাংশনটি অ্যাড-অন স্ক্রিপ্ট প্রকল্পে সংজ্ঞায়িত করে। এই ফাংশন কার্ড তৈরি করে না; পরিবর্তে এটি কিছু অন্যান্য ব্যাকগ্রাউন্ড কাজ করে যা UI পরিবর্তন করে না। যেহেতু ফাংশনটি একটি UniversalActionResponse ফেরত দেয় না, ফাংশনটি শেষ হলে UI একটি নতুন কার্ড প্রদর্শন করে না। পরিবর্তে ফাংশন চলাকালীন UI একটি লোডিং সূচক স্পিনার প্রদর্শন করে।

আপনি কিভাবে openContactURL() , createSettingsResponse() , এবং runBackgroundSync() ফাংশন তৈরি করতে পারেন তার একটি উদাহরণ এখানে দেওয়া হল:

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}