الأدلّة

حزمة أندرويد

تثبيت واستخدام io.navvo:maps-android — عرض خرائط NavvoMapView لتطبيقات Kotlin مع عميل NavvoServices كامل للبحث والترميز الجغرافي والأماكن والتوجيه وحركة المرور والمزيد.

حزمة أندرويد

توفر مكتبة io.navvo:maps-android الرسمية أمرين:

NavvoMapView — عرض خريطة Navvo تفاعلي قابل للتضمين (الكاميرا، الدبابيس، تبديل الأنماط، طبقات GeoJSON) يشير إلى GET /tiles/style لدى Navvo.
NavvoServices — عميل قائم على الـ coroutines لخدمة Navvo (البحث، الترميز الجغرافي، الأماكن، التوجيه، حركة المرور، المصفوفات، مناطق الوصول، الطقس، الشحن الكهربائي، النقل العام…).

كل شيء بهوية Navvo ولا يستدعي سوى https://navvo.io/api/v1. الإحداثيات موحّدة بشكل LatLng(lat, lng).

منذ الإصدار 0.2.0 تتضمن الحزمة أيضًا طبقة أندرويد أوتو (Android Auto) اختيارية (io.navvo.maps.car) — الخريطة نفسها على شاشة السيارة — كما أن العرض غير مقيّد بالحجم، لذا تعمل الأجهزة اللوحية والأجهزة القابلة للطي وأجهزة Chromebook دون أي إعداد إضافي.

المتطلبات: أندرويد 5.0+ (minSdk 21) · Kotlin 1.9+ · JDK 17 / AGP 8.2+ · يتطلب أندرويد أوتو إضافة androidx.car.app:app.

التثبيت

نزّل مصدر المكتبة من docs.navvo.io/sdks وأضفه كوحدة Gradle (أو انشره إلى مستودع Maven الخاص بك)، ثم:

dependencies {
    implementation("io.navvo:maps-android:0.2.0")
}

التهيئة

NavvoMaps.initialize(apiKey = "nvvo_YOUR_KEY")

وفّر مفتاح الواجهة. بدون مفتاح تُعرض الخريطة بعلامة مائية "Navvo Map Developer (Provide Your API Key)" على كل بلاطة. إسناد الخريطة © Navvo.

عرض خريطة

val mapView = NavvoMapView(context).apply {
    setStyle(NavvoMapStyle.STANDARD)
    moveCamera(CameraPosition(target = LatLng(31.9539, 35.9106), zoom = 12.0))
    addMarker(NavvoMarker(id = "a", position = LatLng(31.9539, 35.9106)))
}

استخدام الخدمات (بدون خريطة)

val svc = NavvoServices.instance

val result = svc.search("قهوة في عبدون", near = LatLng(31.95, 35.91), limit = 8)
val plan = svc.plan(RoutePlanRequest(
    locations = listOf(PlanStop(LatLng(31.95, 35.91)), PlanStop(LatLng(31.99, 35.95))),
    costing = RouteCosting.AUTO,
))

أندرويد أوتو (Android Auto)

تعرض حزمة io.navvo.maps.car (منذ 0.2.0) خريطة Navvo على شاشة السيارة عبر مكتبة androidx للتطبيقات داخل السيارة، مع واجهة قوالب آمنة فوقها — دون حزمة سيارة منفصلة:

الصنف	الدور
`NavvoCarAppService` / `NavvoCarSession`	نقطة دخول السيارة جاهزة للإعلان في الـ manifest (مع التحقق من المضيف)؛ ورّثهما للتخصيص.
`NavvoCarMapScreen`	شاشة الخريطة الأساسية — `NavigationTemplate` مع شريط إجراءات للتكبير/التصغير فوق الخريطة الحيّة.
`NavvoCarNavigationScreen`	هيكل ملاحة خطوة-بخطوة: `updateStep(cue, meters)`، `updateDestination(meters, seconds, arrivalMillis)`، `clearNavigationInfo()`.
`NavvoCarMapRenderer`	يرسم الخريطة على سطح السيارة ويحوّل إيماءات المضيف (سحب/تكبير) إلى حركات كاميرا؛ `screen.renderer.getMapAsync { map -> … }` يعطيك `NavvoMapController` المعتاد.

1. أضف مكتبة السيارة بجانب الحزمة (الحزمة نفسها تُجمَّع ضدها بـ compileOnly، فتطبيقات الهاتف فقط لا تحمل شيئًا):

dependencies {
    implementation("io.navvo:maps-android:0.2.0")
    implementation("androidx.car.app:app:1.4.0")
}

2. أعلن الخدمة وبيانات السيارة في ملف AndroidManifest.xml الخاص بتطبيقك:

<uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
<uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES" />

<application>
    <meta-data android:name="androidx.car.app.minCarApiLevel" android:value="1" />
    <meta-data
        android:name="com.google.android.gms.car.application"
        android:resource="@xml/automotive_app_desc" />

    <service
        android:name="io.navvo.maps.car.NavvoCarAppService"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.car.app.CarAppService" />
            <category android:name="androidx.car.app.category.NAVIGATION" />
        </intent-filter>
    </service>
</application>

مع الملف res/xml/automotive_app_desc.xml:

<automotiveApp>
    <uses name="template" />
</automotiveApp>

3. خصّص الشاشة (استدعاء NavvoMaps.initialize من Application.onCreate يغطي جلسة السيارة أيضًا — نفس العملية ونفس المفتاح):

class MyCarSession : NavvoCarSession() {
    override fun onCreateScreen(intent: Intent): Screen =
        object : NavvoCarNavigationScreen(carContext) {}.also { screen ->
            screen.renderer.getMapAsync { map ->
                map.moveCamera(CameraPosition(target = LatLng(31.95, 35.91), zoom = 13.0))
            }
            screen.updateStep("انعطف يمينًا إلى شارع الرينبو", 320.0)
        }
}

اختبر عبر وحدة Desktop Head Unit من أندرويد؛ نسخ التصحيح تقبل أي مضيف، ونسخ الإصدار لا تثق إلا بمضيفي Android Auto المعروفين.

الأجهزة اللوحية والشاشات الكبيرة لا تحتاج شيئًا إطلاقًا: NavvoMapView هو FrameLayout عادي غير مقيّد بالحجم يملأ أي أبعاد يمنحها له التخطيط — هواتف وأجهزة لوحية وقابلة للطي وأجهزة Chromebook، وبأي اتجاه.

الأخطاء

كل استدعاء يرمي صنفًا مشتقًا من NavvoException: ‏NavvoAuthError (401)، NavvoScopeError (403)، NavvoNotFoundError (404)، NavvoValidationError (400/422)، NavvoRateLimitError (429 مع احترام Retry-After)، NavvoServerError (5xx)، NavvoNetworkError/NavvoTimeoutError. تعيد place(slug) القيمة null للمعرّفات غير الموجودة.

حزمة تطوير Flutter

ثبّت واستخدم حزمة navvo_maps_flutter الرسمية — عنصر خريطة NavvoMap القابل للتضمين إضافةً إلى عميل NavvoServices بلغة Dart للبحث والترميز الجغرافي والأماكن والتوجيه وحركة المرور والمزيد.

حزمة iOS

تثبيت واستخدام حزمة NavvoMaps بلغة Swift — عرض NavvoMapView لواجهات UIKit/SwiftUI مع عميل NavvoServices غير متزامن للبحث والترميز الجغرافي والأماكن والتوجيه والمزيد.