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

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

للترويج لميزات تطبيقك وتسهيل استخدامه، يمكنك اقتراح اختصارات "مساعد Google" إلى المستخدمين اختصارات "مساعد 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
الإصدار 6.0 من نظام التشغيل Android (المستوى 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، ستستخدم حزمة SDK مُنفِّذ سلسلة تعليمات واحدة للمهمة.

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

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

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

تمرير هدف الاختصار إلى الطريقة 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 intent الذي استخدامها لبدء نشاط اقتراح الاختصارات في سياق التطبيق.

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، أريد بدء جولة ركض" كاختصار، استبدِع PHRASE ب"start a run".

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

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

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

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

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

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

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