أغراض خرائط Google لنظام التشغيل Android Automotive

باستخدام Android intents، يمكنك بدء التنقّل في "خرائط Google" على Android Automotive.

نظرة عامة

توضّح هذه الصفحة النوايا التي يمكنك استخدامها مع "خرائط Google" في Android Automotive. للحصول على مستندات تفصيلية حول مطوّري تطبيقات Android، يُرجى الاطّلاع على ما يلي:

• الأهداف وفلاتر الأهداف
• الأهداف الشائعة في منصة Android

طلبات تحديد النية

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

• الإجراء يتم استدعاء جميع أغراض "خرائط Google" كإجراء عرض، ACTION_VIEW.

• معرّف الموارد المنتظم (URI) تستخدم نوايا "خرائط Google" سلاسل مرمّزة باستخدام معرّف الموارد المنتظم (URI) تحدّد إجراءً مختارًا، بالإضافة إلى بعض البيانات التي يتم تنفيذ الإجراء بها.

• الحزمة: يضمن الاتصال setPackage("com.google.android.apps.maps") أن يتعامل تطبيق "خرائط Google" على Android مع Intent. إذا لم يتم ضبط الحزمة، سيحدّد النظام التطبيقات التي يمكنها معالجة Intent. إذا توفّرت تطبيقات متعددة، قد يُطلب منك تحديد التطبيق الذي تريد استخدامه.

بعد إنشاء Intent، يمكنك طلب أن يطلق النظام التطبيق ذي الصلة بعدة طرق. تتمثّل إحدى الطرق الشائعة في تمرير Intent إلى الطريقة startActivity(). سيشغّل النظام التطبيق اللازم، وهو في هذه الحالة "خرائط Google"، وسيبدأ Activity المقابل.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

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

للتحقّق من أنّ التطبيق متاح لتلقّي الغرض، استدعِ الدالة resolveActivity() على عنصر Intent. إذا كانت النتيجة غير فارغة، يعني ذلك أنّه يتوفّر تطبيق واحد على الأقل يمكنه التعامل مع الغرض، ويمكنك بأمان استدعاء startActivity(). إذا كانت النتيجة فارغة، يجب عدم استخدام الغرض، وإذا أمكن، إيقاف الميزة التي تستدعي الغرض.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

على سبيل المثال، لبدء التنقّل خطوة بخطوة إلى حديقة حيوانات تارونغا في سيدني، يمكنك استخدام الرمز التالي:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

سلاسل طلب البحث المرمّزة باستخدام معرّف الموارد المنتظم (URI)

يجب ترميز جميع السلاسل التي يتم تمريرها إلى أغراض "خرائط Google" باستخدام معرّف الموارد المنتظم (URI). على سبيل المثال، يجب أن تصبح السلسلة "1st & Pike, Seattle" 1st%20%26%20Pike%2C%20Seattle. يمكن ترميز المسافات في السلسلة باستخدام %20 أو استبدالها بعلامة الجمع (+).

يمكنك استخدام الطريقة android.net.Uri encode() لترميز السلاسل. على سبيل المثال:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

عرض خريطة

استخدِم الغرض geo: لعرض خريطة في موقع جغرافي ومستوى تكبير/تصغير محدّدَين. مثلاً:

geo:latitude,longitude?z=zoom

المعلمات

• تحدّد latitude وlongitude نقطة مركز الخريطة.

• z يضبط بشكل اختياري مستوى التكبير/التصغير الأولي للخريطة. تتراوح القيم المقبولة بين 0 (العالم بأسره) و21 (المباني الفردية). يمكن أن يختلف الحدّ الأقصى حسب بيانات الخريطة المتوفّرة في الموقع الجغرافي المحدّد.

مثال

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

البحث عن موقع جغرافي

استخدِم هذا الغرض لعرض طلبات البحث ضمن إطار عرض محدّد:

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

المعلمات

بالإضافة إلى المَعلمات المستخدَمة لعرض خريطة، يتيح "بحث Google" استخدام المَعلمة التالية:

• تحدّد q الأماكن التي يجب تمييزها على الخريطة. المَعلمة q مطلوبة لجميع طلبات البحث. تقبل هذه السمة موقعًا جغرافيًا كاسم مكان أو عنوان. يجب أن تكون السلسلة متوافقة مع عناوين URL، لذا يجب تحويل عنوان مثل "City Hall, New York, NY" إلى City+Hall%2CNew+York%2CNY.

تحسين نتائج البحث باستخدام الإحداثيات

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

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

تؤدي إضافة خط العرض والطول إلى معرّف الموارد المنتظم (URI) الخاص بالغرض إلى تحيّز النتائج نحو منطقة معيّنة:

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

البحث على طول المسار

إذا تم إرسال طلب بحث geo:latitude,longitude?q=query أثناء التنقّل، سيؤدي ذلك إلى بدء البحث على طول المسار وسيتم تجاهل خط العرض وخط الطول.

البحث عن فئات محدَّدة مسبقًا

لإتاحة التكامل مع المركبة، تتيح "خرائط Google" في السيارة استخدام intent يعرض الفئات المحدّدة مسبقًا التالية:

يكون الغرض من الفئة بالتنسيق geo:lat,lng?c=category.

استخدِم c=<pre-defined category> بغض النظر عن إعدادات اللغة لدى المستخدم. تعرض "خرائط Google" نتائج ذات صلة باللغة المناسبة لهذه الفئة. مثلاً:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

البحث حسب الفئات الأخرى

إذا أدخلت عبارة بحث عامة (مثل "مطاعم" أو "مقاهي") بلغة المستخدم، ستبحث "خرائط Google" على Android Automotive عن بيانات الأنشطة التجارية التي تتطابق مع المعايير. إذا تم توفير خط طول وعرض محدّدين في طلب geo:، سيتم توسيط البحث حول هذا الموقع الجغرافي. في حال عدم تحديد موقع جغرافي (مثلاً، geo:0,0)، تحاول "خرائط Google" العثور على بطاقات بيانات الأنشطة التجارية القريبة. مثلاً:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

يمكنك زيادة تحسين نتائج البحث من خلال تحديد مَعلمة تكبير/تصغير مع سلسلة طلب البحث. في المثال التالي، تؤدي إضافة مستوى تكبير يبلغ 10 إلى محاولة العثور على مطاعم على مستوى المدينة بدلاً من المطاعم القريبة:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

بدء التنقّل باتّجاهات مفصّلة

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

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

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

المعلمات

لبدء التنقّل، استخدِم place أو q مع waypoints، وهو أمر اختياري. لتمييز نقطة توقّف بشكل اختياري كمحطة شحن، اطّلِع على إرسال خطة رحلة بمركبة كهربائية إلى "خرائط Google".

• يضبط q نقطة النهاية لعمليات البحث المتعلقة بالتنقّل. يمكن أن يكون ذلك عبارة عن خط عرض وخط طول أو عنوان منسَّق حسب طلب البحث. إذا كان سلسلة طلب بحث تعرض أكثر من نتيجة واحدة، سيتم اختيار النتيجة الأولى.

• يضبط place نقطة النهاية على المنزل أو العمل. حدِّد home للتنقّل إلى منزل المستخدم، وwork للتنقّل إلى مكان عمل المستخدم.

• تحدّد avoid الميزات التي يجب أن يحاول المسار تجنُّبها. avoid هو حقل اختياري ويمكن ضبطه على قيمة واحدة أو أكثر من القيم التالية:

  • ‫t لرسوم العبور
  • h للطرق السريعة
  • ‫f للعبّارات

• تحدّد waypoints مكانًا وسيطًا واحدًا أو أكثر لتوجيه الاتجاهات إلى الوجهة النهائية المحدّدة بواسطة q. يمكنك تحديد نقاط توقّف متعدّدة باستخدام حرف الشرطة العمودية (|) للفصل بين الأماكن، مثلاً، Berlin,Germany|Paris,France. يمكنك استخدام أي عدد تريده من نقاط الطريق. ستتم إضافة نقاط الطريق إلى المسار بالترتيب نفسه الذي تظهر به في عنوان URL. يمكن أن تكون كل نقطة طريق إما عنوانًا أو إحداثيات خطوط الطول والعرض مفصولة بفواصل، ويمكنك تضمين عناوين وإحداثيات خطوط الطول والعرض في النية نفسها. يجب أن تكون السلاسل مُعدَّلة لتتوافق مع عناوين URL، لذا يجب تحويل نقاط الطريق مثل "Berlin,Germany|Paris,France" إلى Berlin%2CGermany%7CParis%2CFrance.

أمثلة

سيطلب هذا Intent توجيهًا تفصيليًا إلى "حديقة حيوانات تارونغا" في سيدني، أستراليا:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

إذا كنت تفضّل عدم دفع رسوم المرور أو ركوب عبّارة، يمكنك طلب مسار يحاول تجنُّب هذه الحالات:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

أو إذا كنت تفضّل الانتقال إلى منزلك، استخدِم:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

لإطلاق ميزة "الملاحة خطوة بخطوة" إلى العناوين الثلاثة التالية بالترتيب، مرِّر "حديقة حيوانات تارونغا" كوجهة نهائية q، و"مكتب Google في سيدني" و"دار أوبرا سيدني" كنقاط توقّف:

1. ‫Google سيدني

2. دار أوبرا سيدني

3. حديقة حيوانات "تارونغا" في سيدني، أستراليا

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

على غرار q، يمكنك تمثيل أي من نقاط الطريق باستخدام خط عرض وخط طول مفصولَين بفاصلة بدلاً من عنوان. على سبيل المثال، لتشغيل عملية التنقّل نفسها مع تمرير خطوط الطول والعرض الخاصة بدار أوبرا سيدني بدلاً من العنوان:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

إرسال خطة رحلة بمركبة كهربائية إلى "خرائط Google"

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

بالنسبة إلى محطات الشحن، تكون نوايا الرحلة كما يلي:

• يجب أن يحتوي على اسم وخطوط الطول والعرض
• قد يحتوي اختياريًا على خرج الطاقة، ويُستخدم لاحتساب وقت الشحن

تستخدم Google اسم محطة الشحن وخطوط الطول والعرض للعثور على مكان مطابق لمحطة الشحن وعرض بيانات غنية، مثل أنواع الموصلات وإجمالي عددها وسرعاتها ومدى توفّرها في الوقت الفعلي وطرق الدفع المتوافقة ونقاط الاهتمام الخاصة بالمضيف. على سبيل المثال، اتجاهات القيادة داخل مواقف السيارات الخارجية للجزء الأخير من التنقّل وساعات العمل والتقييمات لضمان تطابق محطات الشحن مع بيانات Google، استخدِم <brand name> محدّدًا، مثل ChargePoint.

المعلمات

تسمح لك المَعلمات التالية بتحديد تفاصيل الوجهة النهائية وأي نقاط توقّف، بما في ذلك تلك المحدّدة كمحطات شحن للمركبات الكهربائية.

الوجهة النهائية

لضبط محطة شحن كوجهة نهائية، استخدِم:

• q: يجب أن يحتوي على قيمة خطوط الطول والعرض لمحطة الشحن.
• ‫q_type: تشير 1 إلى أنّ الوجهة النهائية هي محطة شحن.
• q_name: اسم الوجهة النهائية مطلوبة إذا كانت قيمة q_type هي 1.
• ‫q_power_output_kw: تمثّل هذه السمة رقمًا مزدوجًا يشير إلى مقدار الطاقة التي توفّرها محطة الشحن بالكيلوواط. اختيارية:

نقاط الطريق

بالنسبة إلى نقاط الطريق، تكون جميع المَعلمات عبارة عن مصفوفات متوازية مفصولة بعلامة الأنابيب (|) من القيم بالترتيب نفسه كنقاط الطريق، باستثناء الوجهة النهائية. يتم التعامل مع عدم تطابق عدد العناصر في المصفوفات المتوازية على أنّه غرض غير صالح.

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

• waypoints: قائمة بنقاط الطريق كما هو موضّح في نية التنقّل خطوة بخطوة. يجب أن تكون قيمة خطوط الطول والعرض لنقاط طريق محطة الشحن.

• waypoint_types: أنواع نقاط الطريق المحدّدة كرقم 0 هي أي محطة توقّف (القيمة التلقائية)، و1 هي محطة شحن.

• waypoint_names: أسماء نقاط الطريق هذا الحقل إلزامي لمحطات الشحن.

• waypoint_power_outputs_kw: تمثّل هذه السمة أرقامًا مضاعفة لقوة محطة الشحن بالكيلوواط. بالنسبة إلى محطات الشحن، يمكنك اختياريًا تحديد قيمة إنتاج الطاقة لنقطة الطريق، والتي يتم استخدامها كخيار احتياطي في حال عدم العثور على المحطة المطابقة. تعني الفتحة الفارغة أنّه لم يتم تقديم أي قيمة.

سلوك تجربة المستخدم (UX)

بالنسبة إلى طلبات الرحلات التي تتضمّن وجهات متعدّدة، يتم عرض شاشة نظرة عامة على المسار، ولكن لا يبدأ التنقّل تلقائيًا.

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

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

• في حال العثور على تطابق، تستخدم "خرائط Google" بيانات Google لعرض محطة الشحن في واجهة المستخدم وتقديم اقتراح بشأن الشحن في محطة الشحن.

• في حال عدم العثور على تطابق، يتم استخدام البيانات المقدَّمة في الغرض لمحطة شحن (خطوط الطول والعرض والاسم والناتج من الطاقة) لعرض محطة الشحن هذه في واجهة المستخدم وتقديم اقتراح بشأن الشحن في محطة الشحن هذه.

أمثلة

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

الانتقال إلى وجهة نهائية عبر محطات شحن متعددة

يؤدي الغرض التالي إلى الانتقال إلى الوجهة النهائية، Port Macquarie NSW، عبر محطتَي شحن، ChargePoint وEvie.

الوجهات بالترتيب:

1. محطة شحن ChargePoint (الموقع الجغرافي: -32.9599188,151.6240806، الطاقة الناتجة: 6.6 كيلوواط)

2. محطة شحن Evie (الموقع الجغرافي: -31.9432539,152.4699808، إنتاج الطاقة: 350 كيلوواط)

3. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

ناتج الطاقة غير معروف

إذا كانت قيمة خرج الطاقة غير معروفة، اترك الخانة ذات الصلة في waypoint_power_outputs_kw فارغة. أو إذا كانت جميع الخانات فارغة، لن تحتاج إلى تحديد المَعلمة waypoint_power_outputs_kw.

الوجهات بالترتيب:

1. محطة شحن ChargePoint (الموقع الجغرافي: -32.9599188,151.6240806، طاقة الإخراج: غير معروفة)

2. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

وضع علامة على الوجهة النهائية باعتبارها محطة شحن

لوضع علامة على الوجهة النهائية كمحطة شحن، حدِّد المَعلمات q_type وq_name وq_power_output_kw.

الوجهات بالترتيب:

1. حديقة حيوانات "تارونغا" في سيدني، أستراليا

2. محطة شحن ChargePoint (الموقع الجغرافي: ‎-32.9599188,151.6240806، ناتج الطاقة: غير معروف)

3. محطة شحن Evie (الموقع الجغرافي: ‎-31.9432539,152.4699808، ناتج الطاقة: 350 كيلووات)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Intent الإجراء

تتوفّر نوايا الإجراءات التالية مع واجهات: