Android উইজেটের সাথে অ্যাপ অ্যাকশন ইন্টিগ্রেট করা

অনেক ইনটেন্টের ক্ষেত্রে, ব্যবহারকারীকে একটি সহজ উত্তর, সংক্ষিপ্ত কনফার্মেশন বা দ্রুত ইন্টার‍্যাক্টিভ অভিজ্ঞতা প্রদান করাই হল সেরা উত্তর। এই ধরনের ইনটেন্ট পূরণ করতে আপনি Google Assistant-এ Android অ্যাপ উইজেট দেখাতে পারেন।

এই নির্দেশিকায় উইজেট ব্যবহার করে Assistant ব্যবহারকারীর কোয়েরি কীভাবে পূরণ করবেন এবং অ্যাপ অ্যাকশন উইজেট এক্সটেনশন লাইব্রেরি-এর মাধ্যমে Assistant-এর জন্য আপনার উইজেট অভিজ্ঞতা কীভাবে উন্নত করবেন তা কভার করা হয়েছে।

সুবিধা

উইজেট হল অ্যাপ্লিকেশন ভিউয়ের ক্ষুদ্র সংস্করণ যা Android সারফেসে এম্বেড করা যায়, যেমন লঞ্চার বা লক স্ক্রিন। অ্যাপ অ্যাকশনের মাধ্যমে, আপনি Assistant-এ দেখানোর জন্য উপযুক্ত করে আপনার উইজেটের প্রভাব বাড়াতে পারেন:

1. ডিসকভারি: ব্যবহারকারীর ন্যাচারাল ল্যাঙ্গুয়েজ কোয়েরির উত্তরে প্রোঅ্যাক্টিভভাবে উইজেট দেখান।
2. এনগেজমেন্ট: হ্যান্ডস-ফ্রি প্রসঙ্গে উইজেট দেখান, যেমন Assistant যখন লক স্ক্রিনে ব্যক্তিগত ফলাফল প্রদান করে এবং Android Auto-তে।
3. রিটেনশন: ব্যবহারকারীদের Assistant-এ দেখানো উইজেট তাদের লঞ্চারে পিন করতে দিন। পিন করার কার্যকারিতার জন্য উইজেট এক্সটেনশন লাইব্রেরি প্রয়োজন।

Assistant কীভাবে উইজেট দেখায়

ব্যবহারকারীরা Assistant-এ দুটি উপায়ে উইজেট চালু করতে পারেন:

• নাম উল্লেখ করে স্পষ্টভাবে কোনও উইজেটের জন্য অনুরোধ করা।
• Assistant-কে কোনও কোয়েরি বলা যা উইজেট পূরণের জন্য কনফিগার করা বিল্ট-ইন ইনটেন্ট (BII) বা কাস্টম ইনটেন্ট ট্রিগার করে।

এক্সপ্লিসিট ইনভোকেশন

ইনস্টল করা যেকোনও অ্যাপের জন্য এক্সপ্লিসিট ইনভোকেশন উইজেট ব্যবহার করতে, ব্যবহারকারী Assistant-কে এই ধরনের প্রশ্ন করতে পারেন:

• "Ok Google, ExampleApp উইজেট দেখাও।"
• "ExampleApp থেকে পাওয়া উইজেট।"

Assistant এই উইজেটগুলি সাধারণ ভূমিকা সহ দেখায়: "ExampleApp বলে, এখানে একটি উইজেট আছে।" Assistant সাধারণত অ্যাপ ডেভেলপারকে কোনও কাজ করতে না দিয়েই এই পদ্ধতিতে অনুরোধ করা উইজেট ফিরিয়ে দেয়, তবে এই ইনভোকেশন পদ্ধতিতে ব্যবহারকারীকে উইজেট সম্পর্কে স্পষ্ট জ্ঞান থাকতে হবে যাতে তিনি এটির জন্য অনুরোধ করতে পারেন। উইজেট খোঁজার পদ্ধতি সহজ করতে, নিম্নলিখিত বিভাগে বিস্তারিতভাবে উল্লেখ করা ইনটেন্ট ফুলফিলমেন্ট পদ্ধতি ব্যবহার করুন।

ইনটেন্ট ফুলফিলমেন্ট

Assistant-এ ব্যবহারকারীদের করা ন্যাচারাল ল্যাঙ্গুয়েজ কোয়েরি পূরণ করার জন্য আপনার উইজেট ব্যবহার করে, সেগুলি খুঁজে পাওয়া আরও সহজ করুন। যেমন, কোনও ব্যবহারকারী আপনার ফিটনেস অ্যাপে GET_EXERCISE_OBSERVATION BII ট্রিগার করলে, আপনি একটি উইজেট রিটার্ন করতে পারেন। ব্যবহারকারী এই প্রশ্নটি করে ট্রিগার করতে পারেন, "Ok Google, এই সপ্তাহে ExampleApp-এ আমি কত মাইল দৌড়েছি?" খোঁজার প্রসেস সহজ করার পাশাপাশি, অ্যাপ অ্যাকশনের সাথে উইজেট ইন্টিগ্রেট করলে এইসব সুবিধা পাওয়া যায়:

• প্যারামিটার অ্যাক্সেস: Assistant ব্যবহারকারীর কোয়েরি থেকে এক্সট্র্যাক্ট করা ইন্টেন্ট প্যারামিটার আপনার উইজেটে প্রদান করে, যা কাস্টমাইজ করা উত্তর প্রদান করতে সাহায্য করে।
• কাস্টম TTS ভূমিকা: আপনার উইজেট দেখানোর সময় Assistant-এর ঘোষণা করার জন্য আপনি টেক্সট-টু-স্পিচ (TTS) স্ট্রিং প্রদান করতে পারেন।
• উইজেট পিন করা: Assistant আপনার উইজেটের পাশে এই উইজেট যোগ করুন বোতাম দেখায়, যার ফলে ব্যবহারকারীরা সহজেই আপনার উইজেট তাদের লঞ্চারে পিন করতে পারেন।

উইজেট ফুলফিলমেন্ট প্রয়োগ করুন

আপনার ইনটেন্টের জন্য উইজেট ফুলফিলমেন্ট প্রয়োগ করতে, এইসব ধাপ অনুসরণ করুন:

1. সহজ উইজেট তৈরি করুন লিঙ্কে উল্লেখ করা ধাপগুলি অনুসরণ করে Android উইজেট প্রয়োগ করুন।
2. আপনার অ্যাপের shortcuts.xml রিসোর্স ফাইলে, ফুলফিলমেন্টের বিবরণ ও BII <parameter> ট্যাগ সহ আপনার ক্যাপাবিলিটিতে <app-widget> এলিমেন্ট যোগ করুন। প্যারামিটার ম্যানেজ করতে আপনার উইজেট আপডেট করুন।
3. প্রয়োজনীয় Widgets Extension লাইব্রেরি যোগ করুন, যা Assistant-কে আপনার উইজেটে BII নাম ও প্যারামিটার পাস করতে দেয়। এছাড়াও, এটি কাস্টম TTS ভূমিকা এবং উইজেট পিন করা ফাংশনালিটি চালু করে।

নিচের বিভাগে shortcuts.xml-এর জন্য <app-widget> স্কিমা বর্ণনা করা হয়েছে।

উইজেট স্কিমা

<app-widget> এলিমেন্টকে shortcuts.xml-এ <capability> এলিমেন্টের মধ্যে ফুলফিলমেন্ট হিসেবে সংজ্ঞায়িত করা হয়। ঐচ্ছিক হিসেবে উল্লেখ করা না থাকলে, এগুলির জন্য নিম্নলিখিত অ্যাট্রিবিউট প্রয়োজন:

উইজেট স্কিমার বিবরণ

<app-widget>

টপ-লেভেল উইজেট ফুলফিলমেন্ট এলিমেন্ট।

গুণাবলী:

• android:identifier: এই ফুলফিলমেন্টের জন্য শনাক্তকারী। <capability>-এর মধ্যে সংজ্ঞায়িত <app-widget> এবং <intent> ফুলফিলমেন্ট এলিমেন্ট জুড়ে এই ভ্যালু অবশ্যই অনন্য হতে হবে।
• android:targetClass: ইনটেন্ট ম্যানেজ করার জন্য AppWidgetProvider-এর সম্পূর্ণ ক্লাস নেম।

<parameter>

একটি BII প্যারামিটারকে একটি ইনটেন্ট <parameter> ভ্যালুতে ম্যাপ করে। আপনি প্রতিটি <app-widget> এলিমেন্টের জন্য শূন্য বা তার বেশি প্যারামিটার নির্ধারণ করতে পারবেন। ফুলফিলমেন্টের সময়, Assistant উইজেট ইনস্ট্যান্সের জন্য অতিরিক্ত তথ্য কী-ভ্যালু পেয়ার হিসেবে আপডেট করে প্যারামিটার পাস করে, যার ফর্ম্যাট হল:

• কী: প্যারামিটারের জন্য নির্ধারিত android:key।
• ভ্যালু: ব্যবহারকারীর ভয়েস ইনপুট থেকে BII যে ভ্যালু এক্সট্র্যাক্ট করে।

আপনি সংশ্লিষ্ট AppWidgetManager অবজেক্টে getAppWidgetOptions() কল করে এইসব অতিরিক্ত সুবিধা অ্যাক্সেস করতে পারবেন, যা ট্রিগার করা BII-এর নাম ও প্যারামিটার সহ Bundle রিটার্ন করে। আরও বিবরণের জন্য প্যারামিটারের মান এক্সট্র্যাক্ট করুন দেখুন।

BII প্যারামিটার ম্যাচিং সম্পর্কে আরও জানতে, প্যারামিটার ডেটা ও ম্যাচিং দেখুন।

<extra>

এই উইজেটের জন্য কাস্টম TTS ভূমিকা ব্যবহার করা হয়েছে বলে ঘোষণা করা ঐচ্ছিক ট্যাগ। এই ট্যাগের জন্য নিম্নলিখিত অ্যাট্রিবিউট ভ্যালু প্রয়োজন:

• android:name: "hasTts"
• android:value: "true"

নমুনা কোড

shortcuts.xml ফাইল থেকে নেওয়া নিম্নলিখিত উদাহরণে GET_EXERCISE_OBSERVATION BII ক্ষমতার জন্য উইজেট ফুলফিলমেন্ট কনফিগারেশন দেখানো হয়েছে:

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <app-widget
    android:identifier="GET_EXERCISE_OBSERVATION_1"
    android:targetClass="com.exampleapp.providers.exampleAppWidgetProvider"
    android:targetPackage="com.exampleapp">
    <parameter
      android:name="exerciseObservation.aboutExercise.name"
      android:key="exercisename">
    </parameter>
    <extra android:name="hasTts" android:value="true"/>
  </app-widget>
</capability>

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

প্যারামিটারের মান এক্সট্র্যাক্ট করুন

নিচের নমুনা AppWidgetProvider ক্লাসে, প্রাইভেট ফাংশন updateAppWidget() ব্যবহার করা হয় উইজেট বিকল্প Bundle থেকে BII নাম ও প্যারামিটার এক্সট্র্যাক্ট করার জন্য:

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
class MyAppWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // There might be multiple widgets active, so update all of them
        for (appWidgetId in appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId)
        }
    }

    private fun updateAppWidget(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val widgetText: CharSequence = context.getString(R.string.appwidget_text)

        // Construct the RemoteViews object
        val views = RemoteViews(context.packageName, R.layout.my_app_widget)
        views.setTextViewText(R.id.appwidget_text, widgetText)

        // Extract the name and parameters of the BII from the widget options
        val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
        val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII) // "actions.intent.CREATE_TAXI_RESERVATION"
        val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)
        if (params != null && params.containsKey("dropoff")) {
            val dropoffLocation = params.getString("dropoff")
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // There might be multiple widgets active, so update all of them
        for (int appWidgetId : appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId);
        }
    }

    private static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) {

        CharSequence widgetText = context.getString(R.string.appwidget_text);

        // Construct the RemoteViews object
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.my_app_widget);
        views.setTextViewText(R.id.appwidget_text, widgetText);

        // Extract the name and parameters of the BII from the widget options
        Bundle optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId);
        String bii =
                optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII); // "actions.intent.CREATE_TAXI_RESERVATION"
        Bundle params =
                optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS);

        if (params != null && params.containsKey(("dropoff"))){
            String dropoffLocation = params.getString("dropoff");
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }

        appWidgetManager.updateAppWidget(appWidgetId, views);
    }
}

dependencies {
    //...
    implementation "com.google.assistant.appactions:widgets:0.0.1"
}

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
object MyAppWidget : AppWidgetProvider() {
    fun updateAppWidget(
        context: Context?,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
            .setResponseSpeech("Hello world") // TTS to be played back to the user
            .setResponseText("Hello world!") // Response text to be displayed in Assistant
            .build()

        // Update widget with TTS
        appActionsWidgetExtension.updateWidget(appWidgetId)

        // Update widget UI
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

  static void updateAppWidget(Context context, AppWidgetManager appWidgetManager,
    int appWidgetId) {

    AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
      .setResponseSpeech("Hello world")  // TTS to be played back to the user
      .setResponseText("Hello world!")  // Response text to be displayed in Assistant
      .build();

      // Update widget with TTS
      appActionsWidgetExtension.updateWidget(appWidgetId);

      // Update widget UI
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }

}

<application>
  <receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
    android:exported="false">
    <intent-filter>
      <action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
    </intent-filter>
  </receiver>
  <service
    android:name=
    "com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
      <action
        android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
    </intent-filter>
  </service>
</application>

<capability
  android:name="actions.intent.START_EXERCISE">
  <app-widget
    android:identifier="START_EXERCISE_1"
    android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
    <parameter
      android:name="exercise.name"
      android:key="exerciseName"
      app:shortcutMatchRequired="true">
    </parameter>
  </app-widget>
</capability>

<shortcut android:shortcutId="RunningShortcut">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
  <capability-binding
    android:capability="actions.intent.START_EXERCISE"
    android:parameter="exercise.name"
    android:value="running;runs" />
</shortcut>

<shortcuts>
  <capability
    android:name="actions.intent.START_EXERCISE">
    <app-widget
      android:identifier="START_EXERCISE_1"
      android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="exercise.name"
        android:key="exerciseName"
        android:mimeType="text/*">
        <data android:pathPattern="https://exampleapp.com/exercise/.*" />
      </parameter>
    </app-widget>
  </capability>
</shortcuts>

<shortcuts>
  <capability
    android:name="actions.intent.CREATE_TAXI_RESERVATION">
    <!-- Widget with required parameter, specified using the "android:required" attribute. -->
    <app-widget
      android:identifier="CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="taxiReservation.dropoffLocation.name"
        android:key="dropoff"
        android:required="true">
      </parameter>
    </app-widget>
    <!-- Fallback intent with no parameters required to successfully execute. -->
    <intent
      android:identifier="CREATE_TAXI_RESERVATION_3"
      android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.TaxiReservationActivity">
    </intent>
  </capability>
</shortcuts>