للترويج لميزات تطبيقك وتسهيل استخدامه، يمكنك اقتراح اختصارات "مساعد Google" إلى المستخدمين اختصارات "مساعد Google" هي عبارات موجزة يمكن للمستخدم قولها لتشغيل وظائف معيّنة في تطبيقك.
على الرغم من أنّه يمكن للمستخدمين إنشاء اختصارات "مساعد Google" يدويًا، تتيح لك حزمة تطوير البرامج (SDK) لعرض الإعلانات الترويجية داخل التطبيقات اقتراح اختصارات "مساعد Google" وتنفيذها بشكل استباقي. من خلال اقتراح اختصارات، تقدّم للمستخدمين مسارًا واضحًا وبسيطًا للعودة إلى أنشطتهم المفضّلة في تطبيقك بدون الحاجة إلى بذل جهد إضافي لإعداد الاختصارات.
على سبيل المثال، إذا أجرى أحد المستخدمين عملية بحث عن "تمارين موسيقى الميتال الثقيلة" في تطبيق الموسيقى ، يمكنك اقتراح اختصار "مساعد Google" للانتقال مباشرةً إلى نتائج البحث هذه في المستقبل. عند اقتراح اختصار، تظهر رسالة في تطبيقك تطلب من المستخدم تحديد ما إذا كان بإمكانه إنشاء الاختصار.
في هذا المثال، تقترح العبارة "بدء تمرين لياقة بدنية بموسيقى الروك الصاخبة ". يقبل المستخدم الاقتراح ويمكنه بعد ذلك تشغيل الاختصار من خلال قول "Ok Google، أريد بدء تمرين المعدّل العالي."
لمزيد من المعلومات عن طرق توسيع قاعدة جمهور تطبيقك، اطّلِع على مقالة توسيع نطاق وصول تطبيقك باستخدام إجراءات التطبيق.
توفّر حزمة تطوير البرامج (SDK) للإعلانات الترويجية داخل التطبيق الطرق التالية:
lookupShortcut
: يتحقّق مما إذا كان الاختصار الذي تريد اقتراحه قد سبق وتم اقتراحه. الموجودة. تتحقّق الطريقة أيضًا من أي مشاكل تمنع إنشاء ال shortcut . إذا تعذّر إنشاء الاختصار،lookupShortcut
تعرض أسباب ذلك.createShortcutSuggestionIntent
: تعرض هدفًا يمكنك استخدامه من أجل ستطلب من المستخدم إنشاء الاختصار المقترَح.
createShortcutSettingsIntent
: يعرض نية يمكنك استخدامها لنقل المستخدم إلى إعدادات اختصار "مساعد Google" لتطبيقك.
المتطلّبات الأساسية والقيود
يصف هذا القسم المتطلبات الأساسية والمتطلبات لاستخدام الاقتراحات، بالإضافة إلى القيود التي قد تواجهها.
المتطلبات الأساسية للتطوير
لاستخدام الاقتراحات، يجب أن تفي بيئة التطوير لديك بما يلي: المتطلبات الأساسية.
توسيع نطاق تطبيق Android ليعمل على استخدام "مهام التطبيقات"
أدرِج
com.google.android.googlequicksearchbox
ضمن علامة<queries>
في بيان التطبيق. مثلاً:<manifest ...> <queries> <package android:name="com.google.android.googlequicksearchb>ox&<quot; / > /quer<ies ...>
/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
لتحديد ما إذا كان الاختصار الذي تريد اقتراحه صالحًا وما إذا كان الاختصار متوفّرًا حاليًا، إن أمكن.إنشاء هدف لاختصار التطبيق يمثّل هدف الاختصار الاختصار الذي تريد اقتراحه على المستخدم. ينشئ المثال التالي 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();
نقْل نية الاختصار إلى طريقة
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 التي تم عرضها خلال الخطوة السابقة.
تحديد المشاكل في الاقتراحات وحلّها
يسرد هذا القسم المشاكل والاستثناءات التي قد تواجهها عند اقتراح اختصارات.
"GoogleinstallsupportedException: لا يمكن الربط بالخدمة"
بسبب
فلترة مستوى ظهور الحزمة
"GoogleInstallationUnsupportedException
: لا يمكن الربط بالخدمة" قد يحدث في
الإصدار 11 من نظام Android والإصدارات الأحدث تأكَّد من تضمين com.google.android.googlequicksearchbox
داخل علامة <queries>
في ملف البيان:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchb>ox&<quot; /
> /quer<ies
...>
/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" أو حذفه. باستخدام واجهة تطبيق المساعد.
يتم إغلاق نشاط إنشاء الاختصارات على الفور بدون عرض أي محتوى
يمكن أن يتم إغلاق نشاط إنشاء الاختصار بدون عرض أي محتوى إذا لم تنشئ معاينة باستخدام "أداة اختبار إجراءات التطبيقات" أو إذا انتهت صلاحية المعاينة . يُرجى تعديل المعاينة وإعادة المحاولة.