Navvo
الأدلّة

حزمة iOS

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

حزمة iOS

توفر حزمة NavvoMaps الرسمية بلغة Swift أمرين:

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

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

منذ الإصدار 0.2.0 تتضمن الحزمة أيضًا دعم CarPlay المدمج (NavvoCarPlayController + NavvoCarPlaySceneDelegate، محمي بشروط التجميع فلا يكلّف شيئًا بدون التصريح)، وهي تعمل على iPhone وiPad على حد سواء — وعلى macOS عبر وضع مصمَّم لـ iPad.

المتطلبات: iOS 13+ · Swift 5.9+ · يتطلب CarPlay تصريح Apple ‏com.apple.developer.carplay-maps.

التثبيت

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

التهيئة

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

عرض خريطة

// SwiftUI
NavvoMap(style: .standard, camera: .init(target: LatLng(31.9539, 35.9106), zoom: 12))
    .markers([NavvoMarker(id: "a", position: LatLng(31.9539, 35.9106))])

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

let svc = NavvoServices.shared

let result = try await svc.search("قهوة في عبدون", near: LatLng(31.95, 35.91), limit: 8)
let plan = try await svc.plan(RoutePlanRequest(
    locations: [PlanStop(LatLng(31.95, 35.91)), PlanStop(LatLng(31.99, 35.95))],
    costing: .auto
))

CarPlay

دعم CarPlay مدمج في الحزمة (منذ 0.2.0): عرض NavvoMapView حقيقي يملأ شاشة السيارة تحت CPMapTemplate مع أزرار تكبير/تحريك، إضافة إلى هيكل ملاحة خطوة-بخطوة (معاينة الرحلة ← CPNavigationSession ← تحديثات المناورة والوقت المتوقع للوصول). كل الشيفرة محمية بـ #if canImport(CarPlay) مع @available(iOS 13.0, *)، فتُبنى الحزمة كما هي للتطبيقات التي لا تستخدم CarPlay.

1. التصريح — اطلب صلاحية CarPlay من Apple، ثم أضف إلى ملف .entitlements:

<key>com.apple.developer.carplay-maps</key>
<true/>

2. بيان المشهد (Scene manifest) — أعلن مشهد CarPlay في Info.plist مشيرًا إلى المندوب الجاهز (أو صنفك الوارث منه):

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <true/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>CPTemplateApplicationSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>NavvoCarPlay</string>
                <key>UISceneDelegateClassName</key>
                <string>NavvoMaps.NavvoCarPlaySceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

3. استخدام المتحكم — ورّث مندوب المشهد لضبط الخريطة وتغذية الملاحة من منطق الإرشاد لديك:

final class CarPlaySceneDelegate: NavvoCarPlaySceneDelegate, NavvoCarPlayControllerDelegate {
    override func carPlayDidConnect(_ controller: NavvoCarPlayController) {
        controller.delegate = self
        controller.mapView?.setCamera(
            CameraPosition(target: LatLng(31.95, 35.91), zoom: 13), animated: false
        )
        let trip = controller.makeTrip(
            from: LatLng(31.95, 35.91), originName: "البداية",
            to: LatLng(31.99, 35.86), destinationName: "الصويفية"
        )
        controller.previewTrips([trip])
    }

    func carPlayController(
        _ controller: NavvoCarPlayController, didSelect trip: CPTrip, routeChoice: CPRouteChoice
    ) {
        controller.startNavigation(for: trip)
        controller.updateManeuver(instruction: "انعطف يمينًا إلى شارع الرينبو",
                                  distanceRemainingMeters: 320, timeRemainingSeconds: 45)
        controller.updateTripEstimates(for: trip,
                                       distanceRemainingMeters: 5_400,
                                       timeRemainingSeconds: 11 * 60)
    }
}

اختبر في محاكي CarPlay داخل Xcode (I/O → External Displays → CarPlay) — لا حاجة للتصريح هناك. استدعاء NavvoMaps.configure(apiKey:) عند إقلاع التطبيق يغطي مشهد CarPlay أيضًا.

iPad وmacOS. عرض الخريطة متكيّف بالكامل على iPad ‏(Split View وSlide Over وStage Manager). وعلى macOS شغّل التطبيق عبر مصمَّم لـ iPad على أجهزة Apple silicon — دون أي تغيير؛ كما أن NavvoServices (بلغة Foundation الخالصة) يُجمَّع لـ Mac Catalyst كما هو. لتطبيق سطح مكتب أصلي على Windows/macOS/Linux راجع دليل تطبيقات سطح المكتب.

الأخطاء

كل استدعاء يرمي NavvoError: ‏.auth (401)، .scope (403)، .notFound (404)، .validation (400/422)، .rateLimit(retryAfter:) (429)، .server (5xx)، .network/.timeout. تعيد place(slug) القيمة nil للمعرّفات غير الموجودة.

حزمة أندرويد

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

حزمة React Native

تثبيت واستخدام @navvo/react-native-maps — مكوّن NavvoMapView مع عميل NavvoServices كامل الأنواع للبحث والترميز الجغرافي والأماكن والتوجيه والمزيد.

Copyright © 2026