التنقّل في مسار وجهة واحدة

اتبع هذا الدليل لرسم مسار داخل التطبيق باستخدام حزمة SDK للتنقل لنظام Android. يفترض هذا الدليل أنك قد دمجت بالفعل حزمة SDK للتنقل في تطبيقك، كما هو موضح في إعداد مشروعك.

ملخّص

  1. إضافة عنصر واجهة مستخدم إلى تطبيقك، إما كجزء من التنقل أو كعرض تنقّل. يضيف عنصر واجهة المستخدم هذا الخريطة التفاعلية وواجهة مستخدم التنقل خطوة بخطوة إلى نشاطك.
  2. طلب أذونات تحديد الموقع الجغرافي يجب أن يطلب تطبيقك إذن تحديد الموقع الجغرافي لتحديد موقع الجهاز
  3. عليك إعداد حزمة تطوير البرامج (SDK) باستخدام الفئة NavigationApi.

  4. يمكنك تحديد وجهة والتحكّم في التنقّل باتّجاهات مفصّلة باستخدام الفئة Navigator. يتضمن ذلك ثلاث خطوات:

    • تحديد الوجهة باستخدام setDestination().
    • بدء التنقّل باستخدام startGuidance().
    • استخدِم getSimulator() لمحاكاة تقدم المركبة على المسار، لاختبار تطبيقك وتصحيح الأخطاء وعرض التطبيق.

  5. إنشاء تطبيقك وتشغيله

الاطّلاع على الرمز

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

يتناول هذا القسم طريقتَين يمكنك من خلالهما إضافة الخريطة التفاعلية وواجهة المستخدم لعرض التنقّل باتّجاهات مفصّلة.

SupportNavigationFragment هو مكون واجهة المستخدم الذي يعرض الإخراج المرئي للتنقل، بما في ذلك الخريطة التفاعلية والاتجاهات منعطف بمنعطف. يمكنك الإعلان عن الجزء في ملف تنسيق XML كما هو موضح هنا:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

ويمكنك بدلاً من ذلك إنشاء الجزء آليًا، كما هو موضّح في مستندات Android، باستخدام FragmentActivity.getSupportFragmentManager().

كبديل للجزء، يتوفّر أيضًا مكوِّن واجهة المستخدم لعرض خريطة للتنقّل على شكل NavigationView.

طلب إذن تحديد الموقع الجغرافي

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

  1. أضِف الإذن كعنصر ثانوي للعنصر <manifest> في بيان Android:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.navsdksingledestination">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

  2. اطلب أذونات التشغيل في تطبيقك، ما يمنح المستخدم فرصة منح أو رفض إذن تحديد الموقع الجغرافي. يتحقق الرمز التالي مما إذا كان المستخدم قد منحك إذن تحديد الموقع المناسب إذا لم يكن كذلك، سيطلب الإذن:

    if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
        android.Manifest.permission.ACCESS_FINE_LOCATION)
            == PackageManager.PERMISSION_GRANTED) {
    mLocationPermissionGranted = true;
} else {
    ActivityCompat.requestPermissions(this,
            new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
            PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
}

if (!mLocationPermissionGranted) {
    displayMessage("Error loading Navigation SDK: "
            + "The user has not granted location permission.");
    return;
}

  3. يمكنك إلغاء معاودة الاتصال بـ onRequestPermissionsResult() لمعالجة نتيجة طلب الإذن:

    @Override
public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                       @NonNull int[] grantResults) {
    mLocationPermissionGranted = false;
    switch (requestCode) {
        case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
            // If request is canceled, the result arrays are empty.
            if (grantResults.length > 0
                    && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                mLocationPermissionGranted = true;
            }
        }
    }
}

إعداد حزمة تطوير البرامج (SDK) للتنقّل

توفر فئة NavigationApi منطق إعداد يفوّض تطبيقك باستخدام التنقّل على Google. يغطي هذا القسم كيفية تهيئة أداة التنقل، إلى جانب بعض التهيئات الأخرى التي يمكنك تفعيلها لتطبيقك:

  1. عليك إعداد حزمة تطوير البرامج (SDK) للتنقّل وإلغاء معاودة الاتصال بـ onNavigatorReady() لبدء التنقّل عندما يكون برنامج التنقّل جاهزًا.

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

  3. اختياريّ. يمكنك تفعيل قيود الطرق في البلدان التي تتوفر فيها الميزة. قم بتعيين الرقم الأخير من لوحة ترخيص. ويجب إجراء هذا الطلب مرة واحدة فقط: تستمر طلبات الاتجاهات اللاحقة في استخدامه. لا يمكن إجراء هذه المكالمة إلّا في المناطق التي تتوفّر فيها الميزة. يمكنك الاطّلاع على Countries and regions supported for two-wheeled vehicles.

    NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
            /**
             * Sets up the navigation UI when the navigator is ready for use.
             */
            @Override
            public void onNavigatorReady(Navigator navigator) {
                displayMessage("Navigator ready.");
                mNavigator = navigator;
                mNavFragment = (NavigationFragment) getFragmentManager()
                        .findFragmentById(R.id.navigation_fragment);

                // Optional. Disable the guidance notifications and shut down the app
                // and background service when the user closes the app.
                // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

                // Optional. Set the last digit of the car's license plate to get
                // route restrictions for supported countries.
                // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");

                // Set the camera to follow the device location with 'TILTED' driving view.
                mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);

                // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI).
                mRoutingOptions = new RoutingOptions();
                mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);

                // Navigate to a place, specified by Place ID.
                navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
            }

            /**
             * Handles errors from the Navigation SDK.
             * @param errorCode The error code returned by the navigator.
             */
            @Override
            public void onError(@NavigationApi.ErrorCode int errorCode) {
                switch (errorCode) {
                    case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                        displayMessage("Error loading Navigation SDK: Your API key is "
                                + "invalid or not authorized to use the Navigation SDK.");
                        break;
                    case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                        displayMessage("Error loading Navigation SDK: User did not accept "
                                + "the Navigation Terms of Use.");
                        break;
                    case NavigationApi.ErrorCode.NETWORK_ERROR:
                        displayMessage("Error loading Navigation SDK: Network error.");
                        break;
                    case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                        displayMessage("Error loading Navigation SDK: Location permission "
                                + "is missing.");
                        break;
                    default:
                        displayMessage("Error loading Navigation SDK: " + errorCode);
                }
            }
        });

تحديد وجهة

توفر الفئة Navigator إمكانية التحكم في ضبط رحلة التنقل وبدئها وإيقافها.

باستخدام Navigator الذي تم الحصول عليه في القسم السابق، حدد وجهة Waypoint لهذه الرحلة. بعد حساب الاتجاهات، يعرض عنصر SupportNavigationFragment خطًا متعدد الخطوط يمثّل المسار على الخريطة، فضلاً عن علامة تشير إلى الوجهة.

    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

        // Create a future to await the result of the asynchronous navigator task.
        ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
                mNavigator.setDestination(destination, travelMode);

        // Define the action to perform when the SDK has determined the route.
        pendingRoute.setOnResultListener(
                new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                    @Override
                    public void onResult(Navigator.RouteStatus code) {
                        switch (code) {
                            case OK:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // Enable voice audio guidance (through the device speaker).
                                mNavigator.setAudioGuidance(
                                        Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                                // Simulate vehicle progress along the route for demo/debug builds.
                                if (BuildConfig.DEBUG) {
                                    mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                            new SimulationOptions().speedMultiplier(5));
                                }

                                // Start turn-by-turn guidance along the current route.
                                mNavigator.startGuidance();
                                break;
                            // Handle error conditions returned by the navigator.
                            case NO_ROUTE_FOUND:
                                displayMessage("Error starting navigation: No route found.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

إنشاء تطبيقك وتشغيله

  1. وصِّل جهاز Android بجهاز الكمبيوتر. يُرجى اتّباع تعليمات "استوديو Android" حول كيفية تشغيل التطبيقات على جهاز بدلاً من ذلك، يمكنك ضبط جهاز افتراضي باستخدام مدير جهاز Android الافتراضي (AVD). عند اختيار المحاكي، تأكد من اختيار صورة تتضمن Google APIs.
  2. في "استوديو Android"، انقر على خيار القائمة تشغيل أو على رمز زر التشغيل. اختَر جهازًا كما هو مطلوب.

نصائح لتحسين تجربة المستخدم

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