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

باستخدام نوايا Android، يمكنك بدء التنقّل في "خرائط 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 الإجراء

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