تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

على الرغم من أنّه يمكن للمستخدمين إنشاء اختصارات "مساعد Google" يدويًا، تتيح لك "حزمة تطوير البرامج (SDK) الترويجية داخل التطبيق" اقتراح اختصارات "مساعد 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 وإعداد برنامج الاقتراحات، ثم تحديد الاقتراحات التي تريد تقديمها للمستخدمين.

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

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

تعريف مثيل 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 أداة تنفيذ ذات سلسلة واحدة للمهمة.

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

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

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 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();

مرِّر هدف الاختصار إلى الطريقة 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));

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

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

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);
    );

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

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

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

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

"GoogleInstallSupportedException: تعذر الربط بالخدمة"

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

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

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

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

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

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