اقتراح اختصارات باستخدام حزمة تطوير البرامج (SDK) للعروض الترويجية داخل التطبيق

للترويج لميزات تطبيقك وتسهيل استخدامه، يمكنك اقتراح اختصارات "مساعد Google" على المستخدمين. اختصارات "مساعد Google" هي عبارات موجزة يمكن للمستخدم قولها لتفعيل وظيفة معيّنة في تطبيقك.

على الرغم من أنّه يمكن للمستخدمين إنشاء اختصارات "مساعد Google" يدويًا، تتيح لك حزمة تطوير البرامج (SDK) للعروض الترويجية داخل التطبيق اقتراح اختصارات "مساعد Google" وتنفيذها بشكل استباقي. من خلال اقتراح الاختصارات، يمكنك أن توفّر للمستخدمين مسارات واضحة وبسيطة للعودة إلى أنشطتهم المفضّلة في تطبيقك بدون بذل جهد إضافي لإعداد الاختصارات.

على سبيل المثال، إذا أجرى مستخدم بحثًا عن "تمارين رياضية على موسيقى الهيفي ميتال" في تطبيق الموسيقى، يمكنك اقتراح اختصار "مساعد Google" مباشرةً لنتائج البحث هذه في المستقبل. عند اقتراح اختصار، يظهر طلب في تطبيقك يعرض العبارة المقترَحة للاختصار ويسأل المستخدم عمّا إذا كان يمكن إنشاء الاختصار.

في هذا المثال، تقترح العبارة، "ابدأ تمرين موسيقى الهيفي ميتال". يقبل المستخدم الاقتراح ويمكنه بعد ذلك تشغيل الاختصار من خلال قول "Ok Google، أريد بدء تمرين الاستماع إلى موسيقى الهيفي ميتال".

لمزيد من المعلومات حول طرق زيادة جمهور تطبيقك، يُرجى الاطّلاع على مقالة تطوير تطبيقك باستخدام إجراءات التطبيقات.

توفّر حزمة SDK للعروض الترويجية داخل التطبيق الطرق التالية:

• lookupShortcut: تتحقّق مما إذا كان الاختصار الذي تريد اقتراحه متوفّرًا من قبل. تتحقّق الطريقة أيضًا من أي مشاكل تمنع إنشاء الاختصار. إذا تعذّر إنشاء الاختصار، تعرض الدالة lookupShortcut الأسباب.

• createShortcutSuggestionIntent: تعرض هذه الطريقة نية يمكنك استخدامها لمطالبة المستخدم بإنشاء الاختصار المقترَح.

• createShortcutSettingsIntent: تعرض هذه الطريقة نية يمكنك استخدامها لنقل المستخدم إلى إعدادات اختصارات "مساعد Google" في تطبيقك.

ملاحظة: لا تتيح حزمة SDK للعروض الترويجية داخل التطبيق استخدام الاختصارات المرتبطة بالنيات المخصّصة.

المتطلبات الأساسية والقيود

يصف هذا القسم المتطلبات الأساسية والمتطلبات اللازمة لاستخدام الاقتراحات بالإضافة إلى القيود التي قد تواجهها.

متطلبات التطوير الأساسية

لاستخدام الاقتراحات، يجب أن تستوفي بيئة التطوير المتطلبات الأساسية التالية.

• يمكنك توسيع نطاق تطبيق Android لاستخدام ميزة "مهامّ في التطبيقات".

• يُرجى تضمين com.google.android.googlequicksearchbox ضمن علامة <queries> في بيان التطبيق. على سبيل المثال:

  <manifest ...>
    <queries>
      <package android:name="com.google.android.googlequicksearchbox" />
    </queries>
    ...
  </manifest>
  

• استخدِم مجموعة حزمات تطبيق Android لنشر تطبيقاتك.

متطلبات الجهاز

لاختبار اقتراحاتك على جهاز، يجب أن يكون جهازك مثبّتًا عليه ما يلي:

• أحدث إصدار من تطبيق Google

• ‫Android 6.0 (مستوى واجهة برمجة التطبيقات 23) أو الإصدارات الأحدث

القيود المعروفة

تتوفّر الاقتراحات باللغة الإنجليزية فقط. لكي تظهر اقتراحاتك للمستخدمين، عليهم ضبط لغة "مساعد Google" على أجهزتهم على الإنجليزية.

تنفيذ الاقتراحات

لتنفيذ الاقتراحات، عليك تعديل ملف build.gradle وإعداد برنامج الاقتراحات، ثم تحديد الاقتراحات التي تريد تقديمها للمستخدمين.

1. أضِف تبعية المكتبة إلى ملف build.gradle.

   dependencies {
     ...
     implementation "com.google.assistant.appactions:suggestions:1.0.0"
   }
   

2. حدِّد مثيلاً لـ AssistantShortcutSuggestionsClient.

   Kotlin

   val shortcutsClient =
     AssistantShortcutSuggestionsClient.builder()
       .setContext(CONTEXT: Context)
       .setVerifyIntents(VERIFY_INTENTS: Boolean)
       .setCustomExecutor(CUSTOM_EXECUTOR: Object)
       .build()

   Java

   AssistantShortcutSuggestionsClient shortcutsClient =
     AssistantShortcutSuggestionsClient.builder()
       .setContext(CONTEXT: Context)
       .setVerifyIntents(VERIFY_INTENTS: Boolean)
       .setCustomExecutor(CUSTOM_EXECUTOR: Object)
       .build();

   في هذا المثال:

   • ‫CONTEXT (مطلوبة) هي سياق التطبيق.

   • يحدّد VERIFY_INTENTS (مطلوب) ما إذا كان سيتم التحقّق من كل نية تم إنشاؤها عند اقتراح اختصارات للمستخدمين. عندما يكون true، يتم التحقّق من الأهداف التي أنشأها AssistantShortcutSuggestionsClient. إذا كان الهدف غير صالح، سيتم عرض استثناء.

   • ‫CUSTOM_EXECUTOR (اختياري) هو منفّذ مخصّص لتشغيل المهام غير المتزامنة. وفي حال عدم توفيره، تستخدم حزمة تطوير البرامج (SDK) منفّذًا أحادي السلسلة للمهمة.

3. استخدِم طريقة lookupShortcut لتحديد ما إذا كان الاختصار الذي تريد اقتراحه صالحًا، وما إذا كان الاختصار متوفّرًا من قبل، إذا أردت ذلك.

   1. أنشئ نية اختصار التطبيق. يمثّل هدف الاختصار الاختصار الذي تريد اقتراحه على المستخدم. ينشئ المثال التالي intent لاختصار لبدء تمرين.

      Kotlin

      val exercise = mapOf(
          "@type" to "Exercise",
          "@context" to "http://schema.googleapis.com",
          "name" to "Running",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .build()
       

      Java

        Map<String, Object> exercise = new HashMap<>();
        exercise.put("@type", "Exercise");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Running");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.START_EXERCISE")
                .setPackageName("my.app.package")
                .setIntentParamName("exercise")
                .setIntentParamValue(exercise)
                .build();
       

   2. مرِّر نية الاختصار إلى الإجراء lookupShortcut.

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
      if (!result.isShortcutPresent) {
          // App can suggest creating a shortcut
      } else {
          // App can remind the user that they have a shortcut for this app action
      }

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // App can suggest creating a shortcut
          } else {
            // App can remind the user that they have a shortcut for this app action
          }
        })
        .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

4. أنشئ الاقتراح باستخدام نية الاختصار. هناك طريقتان يمكنك استخدامهما لإنشاء اقتراح:

   • ‫createShortcutSuggestionIntent: تعرض هذه السمة نية Android التي تستخدمها لبدء نشاط اقتراح الاختصارات في سياق تطبيقك.

     Kotlin

     val exerciseShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand(PHRASE: String)
         .build()
     
     val intent = shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut).await()
     application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

     Java

       AppShortcutSuggestion exerciseShortcut =
           AppShortcutSuggestion.builder()
               .setAppShortcutIntent(appShortcutIntent)
               .setCommand(PHRASE: String)
               .build();
     
       shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut)
           .addOnSuccessListener(intent ->
               getApplication().startActivity(
                   intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
           )
           .addOnFailureListener(e ->
               Log.e(TAG, "Failed to get shortcut suggestion intent", e);
           );

     في هذا المثال، PHRASE هي العبارة التي تريد اقتراحها على المستخدم كاختصار. على سبيل المثال، إذا أردت أن يقول المستخدم "Ok Google, start a run" كاختصار، استبدِل PHRASE بـ "start a run".

     ملاحظة: لا تُدرِج Hey Google في اقتراحك.

     Kotlin

     val exerciseShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand("start a run")
         .build()

     Java

     AppShortcutSuggestion exerciseShortcut =
         AppShortcutSuggestion.builder()
             .setAppShortcutIntent(appShortcutIntent)
             .setCommand("start a run")
             .build();

   • createShortcutSettingsIntent: تعرض هذه الطريقة Android intent ينقل المستخدم إلى واجهة إعدادات الاختصارات في تطبيق "مساعد Google".

     Kotlin

     val intent = shortcutsClient.createShortcutSettingsIntent().await()
     application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

     Java

       shortcutsClient.createShortcutSettingsIntent()
         .addOnSuccessListener(intent ->
             getApplication().startActivity(
                 intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
         )
         .addOnFailureListener(e ->
             Log.e(TAG, "Failed to get shortcut settings intent", e);
         );

5. اتصل بالرقم startActivity باستخدام Android intent الذي تم عرضه خلال الخطوة السابقة.

   ملاحظة: إذا كان الاختصار الذي تقترحه يتعارض مع اختصار حالي، سيظل المستخدم في سياق تطبيقك وسيُطلب منه ضبط عبارة جديدة للاختصار.

اقتراحات تحديد المشاكل وحلّها

يسرد هذا القسم المشاكل والاستثناءات التي قد تواجهها عند اقتراح اختصارات.

"GoogleInstallationUnsupportedException: Cannot bind to service"

بسبب فلترة مستوى ظهور حِزم التطبيقات، قد تظهر رسالة الخطأ "GoogleInstallationUnsupportedException: يتعذّر الربط بالخدمة" على نظام التشغيل Android 11 والإصدارات الأحدث. تأكَّد من تضمين com.google.android.googlequicksearchbox ضمن علامة <queries> في بيان التطبيق:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"تعذّر التحقّق من توقيع APK"

يمكن أن يحدث الخطأ التالي إذا لم ترسِل تطبيقك العلني كحزمة تطبيق:

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

تأكَّد من إرسال تطبيقك كمجموعة حزمات تطبيق Android.

"تعذّر الحصول على اختصارات المستخدم"

قد تظهر رسالة الخطأ "تعذّر الحصول على اختصارات المستخدم" إذا أضفت مؤخرًا حسابًا إلى الجهاز ولم يتم تخزين بيانات اختصارات الحساب الجديد مؤقتًا على الجهاز بعد.

لمزامنة بيانات الاختصارات على الجهاز، يمكنك إضافة اختصار "مساعد Google" أو حذفه باستخدام واجهة تطبيق "مساعد Google".

يتم إغلاق نشاط إنشاء الاختصار على الفور بدون عرض أي محتوى

يمكن إغلاق نشاط إنشاء الاختصار بدون عرض أي محتوى إذا لم تنشئ معاينة باستخدام "أداة اختبار مهام التطبيقات" أو إذا انتهت صلاحية المعاينة. يُرجى تعديل المعاينة وإعادة المحاولة.