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

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

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

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

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

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

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

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

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

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

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

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

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

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

• توسيع نطاق تطبيق 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، ستستخدم حزمة SDK مُنفِّذ سلسلة تعليمات واحدة للمهمة.

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

   1. إنشاء هدف لاختصار التطبيق يمثل الغرض من الاختصار الاختصار الذي تريد اقتراحه للمستخدم. المثال التالي ينشئ نية لاختصار لطلب مشروب.

      Kotlin

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      Java

        Map<String, Object> menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .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 intent الذي استخدامها لبدء نشاط اقتراح الاختصارات في سياق التطبيق.

     Kotlin

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

     Java

       AppShortcutSuggestion orderShortcut =
           AppShortcutSuggestion.builder()
               .setAppShortcutIntent(appShortcutIntent)
               .setCommand(PHRASE: String)
               .build();
     
       shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
           .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، أريد طلب شاي الفقاعات" كاختصار، استبدِل PHRASE مع "order my bubble tea".

     Kotlin

     val orderShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand("order my bubble tea")
         .build()
     

     Java

     AppShortcutSuggestion orderShortcut =
         AppShortcutSuggestion.builder()
             .setAppShortcutIntent(appShortcutIntent)
             .setCommand("order my bubble tea")
             .build();
     

   • createShortcutSettingsIntent: يعرض هدف Android يتحرك المستخدم إلى واجهة إعدادات الاختصارات في تطبيق "مساعد 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 الذي تم عرضه في الخطوة السابقة.

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

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

"Google installsupportedException: لا يمكن الربط بالخدمة"

بسبب فلترة مستوى ظهور الحزمة "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" أو حذفه. باستخدام واجهة تطبيق المساعد.

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

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