تفعيل التنقّل في CarPlay

ملاحظة مُهمة: جميع التطبيقات التي تم تطويرها للاستخدام مع CarPlay تتطلّب الحصول على استحقاق CarPlay من Apple ويجب أن تتّبع إرشادات CarPlay من Apple. يوفّر هذا الدليل ممارسات عادية يجب اتّباعها، ولكن لا يزال عليك إرسال تطبيقك للموافقة عليه قبل أن تتمكّن من إطلاقه في CarPlay. للمزيد من التفاصيل، يمكنك الاطّلاع على دليل برمجة تطبيقات CarPlay من Apple وإرشادات الواجهة البشرية (CarPlay).

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

يمكنك إنشاء تطبيق CarPlay باستخدام مجموعة من نماذج واجهة المستخدم التي تقدّمها Apple. تطبيقك مسؤول عن اختيار النموذج لعرضه وتقديم البيانات داخله.

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

تعرض الصورة اليمنى مثالاً على شاشة التنقّل في CarPlay. تعرض الصورة اليمنى خطوات التنقّل نفسها التي تظهر على الهاتف.

ضبط إعدادات الجهاز

البدء باستخدام CarPlay

أولاً، تعرف على وثائق Apple:

• https://developer.apple.com/carplay/
• https://developer.apple.com/carplay/documentation/CarPlay-App-Programming-Guide.pdf

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

1. بمجرد قراءة وثائق Apple، فأنت على استعداد للعمل باستخدام حزمة SDK للتنقل.
2. قم بإعداد مشروعك إذا لم تكن قد دمجت بالفعل حزمة SDK للتنقل في تطبيقك.
3. فعِّل خلاصة إرشادات TurnByTurn لتطبيقك.
4. اختياريّ. استخدم الأيقونات التي تم إنشاؤها من حزمة SDK للتنقل.
5. ارسم الخريطة باستخدام الفئة GMSMapView المتوفرة في فئة UIView. راجع التنقل في المسار للحصول على مزيد من المعلومات. عليك تعبئة CPNavigationSession بالبيانات من مكتبة TurnByTurn.

رسم واجهة مستخدم الخريطة والتنقّل

تعرض الدورة التدريبية GMSMapView خريطة، وتعرض CPMapTemplate واجهة المستخدم على شاشات CarPlay. وهي توفّر الكثير من الوظائف نفسها المتوفّرة في "GMSMapView" للهواتف، مع مستوى تفاعل محدود.

Swift

init(window: CPWindow) {
    super.init(nibName: nil, bundle: nil)
    self.window = window

    // More CPMapTemplate initialization

}

override func viewDidLoad() {
    super.viewDidLoad()

    let mapViewOptions = GMSMapViewOptions()
    mapViewOptions.screen = window.screen
    mapViewOptions.frame = self.view.bounds

    mapView = GMSMapView(options: mapViewOptions)
    mapView.autoresizingMask = [.flexibleHeight, .flexibleWidth]
    mapView.settings.isNavigationHeaderEnabled = false
    mapView.settings.isNavigationFooterEnabled = false

    // Disable buttons: in CarPlay, no part of the map is clickable.
    // The app should instead place these buttons in the appropriate slots of the CarPlay template.
    mapView.settings.compassButton = false
    mapView.settings.isRecenterButtonEnabled = false
    mapView.shouldDisplaySpeedometer = false
    mapView.isMyLocationEnabled = true

    self.view.addSubview(mapView)
}

Objective-C

- (instancetype)initWithWindow:(CPWindow *)window {
  self = [super initWithNibName:nil bundle:nil];
  if (self) {
    _window = window;

  // More CPMapTemplate initialization
  }
}

- (void)viewDidLoad {
  [super viewDidLoad];
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.screen = _window.screen;
  options.frame = self.view.bounds;
  _mapView = [[GMSMapView alloc] initWithOptions:options];
  _mapView.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth;
  _mapView.settings.navigationHeaderEnabled = NO;
  _mapView.settings.navigationFooterEnabled = NO;

  // Disable buttons: in CarPlay, no part of the map is clickable.
  // The app should instead place these buttons in the appropriate slots of the CarPlay template.
  _mapView.settings.compassButton = NO;
  _mapView.settings.recenterButtonEnabled = NO;

  _mapView.shouldDisplaySpeedometer = NO;
  _mapView.myLocationEnabled = YES;

  [self.view addSubview:_mapView];
}

تفعيل التفاعل مع الخريطة

لضمان سلامة السائق، تفرض خدمة CarPlay حدودًا على التفاعل على سطح الشاشة بسلسلة من طُرق CPMapTemplateDelegate. يمكنك استخدام عمليات معاودة الاتصال هذه لإتاحة تفاعل محدود للسائق مع الخريطة على شاشة السيارة أثناء القيادة.

لإتاحة إجراءات إضافية للمستخدمين، أنشئ مصفوفة من CPMapButton وخصِّصها إلى CPMapTemplate.mapButtons.

تنشئ التعليمة البرمجية التالية تفاعلات التحريك والأزرار للتحريك والتكبير والتصغير ولتوفير موقع المستخدم.

العرض الشامل للتفاعلات

Swift

// MARK: CPMapTemplateDelegate
func mapTemplate(_ mapTemplate: CPMapTemplate, panBeganWith direction: CPMapTemplate.PanDirection) {

}

func mapTemplate(_ mapTemplate: CPMapTemplate, panWith direction: CPMapTemplate.PanDirection) {
    let scrollAmount = scrollAmount(for: direction)
    let scroll = GMSCameraUpdate.scrollBy(x: scrollAmount.x, y: scrollAmount.y)
    mapView.animate(with: scroll)
}

func mapTemplate(_ mapTemplate: CPMapTemplate, panEndedWith direction: CPMapTemplate.PanDirection) {
}

func scrollAmount(for panDirection: CPMapTemplate.PanDirection) -> CGPoint {
    let scrollDistance = 80.0
    var scrollAmount = CGPoint(x: 0, y: 0)
    switch panDirection {
        case .left:
            scrollAmount.x -= scrollDistance
            break;
        case .right:
            scrollAmount.x += scrollDistance
            break;
        case .up:
            scrollAmount.y += scrollDistance
            break;
        case .down:
            scrollAmount.y -= scrollDistance
            break;
        default:
            break;
    }
    if scrollAmount.x != 0 && scrollAmount.y != 0 {
        // Adjust length if scrolling diagonally.
        scrollAmount = CGPointMake(scrollAmount.x * sqrt(1.0/2.0), scrollAmount.y * sqrt(1.0/2.0))
    }
    return scrollAmount
}

Objective-C

#pragma mark - CPMapTemplateDelegate

- (void)mapTemplate:(CPMapTemplate *)mapTemplate panBeganWithDirection:(CPPanDirection)direction {
}

- (void)mapTemplate:(CPMapTemplate *)mapTemplate panWithDirection:(CPPanDirection)direction {
CGPoint scrollAmount = [self scrollAmountForPanDirection:direction];
GMSCameraUpdate *scroll = [GMSCameraUpdate scrollByX:scrollAmount.x Y:scrollAmount.y];
[_mapView animateWithCameraUpdate:scroll];
}

- (void)mapTemplate:(CPMapTemplate *)mapTemplate panEndedWithDirection:(CPPanDirection)direction {
}
- (CGPoint)scrollAmountForPanDirection:(CPPanDirection)direction {
  static const CGFloat scrollDistance = 80.;
  CGPoint scrollAmount = {0., 0.};
  if (direction & CPPanDirectionLeft) {
    scrollAmount.x = -scrollDistance;
  }
  if (direction & CPPanDirectionRight) {
    scrollAmount.x = scrollDistance;
  }
  if (direction & CPPanDirectionUp) {
    scrollAmount.y = -scrollDistance;
  }
  if (direction & CPPanDirectionDown) {
    scrollAmount.y = scrollDistance;
  }
  if (scrollAmount.x != 0 && scrollAmount.y != 0) {
  // Adjust length if scrolling diagonally.
  scrollAmount =
    CGPointMake(scrollAmount.x * (CGFloat)M_SQRT1_2, scrollAmount.y * (CGFloat)M_SQRT1_2);
  }
  return scrollAmount;
}

الاستخدامات الشائعة للأزرار

Swift

// MARK: Create Buttons

func createMapButtons() -> [CPMapButton] {
    let panButton = mapButton(systemImageName: "dpad.fill") { [weak self] in
        self?.didTapPanButton()
    }

    let zoomOutButton = mapButton(systemImageName: "minus.magnifyingglass") { [weak self] in
        self?.didTapZoomOutButton()
    }

    let zoomInButton = mapButton(systemImageName: "plus.magnifyingglass") { [weak self] in
        self?.didTapZoomInButton()
    }

    let myLocationButton = mapButton(systemImageName: "location") { [weak self] in
        self?.didTapMyLocationButton()
    }

    let mapButtons = [panButton, zoomOutButton, zoomInButton, myLocationButton]
    return mapButtons
}

func mapButton(systemImageName: String, handler: @escaping () -> Void) -> CPMapButton {

}


// MARK: Button callbacks

@objc func didTapPanButton() {
    mapTemplate?.showPanningInterface(animated: true)
}

@objc func didTapZoomOutButton() {
    mapView.animate(with: GMSCameraUpdate.zoomOut())
}

@objc func didTapZoomInButton() {
    mapView.animate(with: GMSCameraUpdate.zoomIn())
}

@objc func didTapMyLocationButton() {
    if let lastLocation = lastLocation {
        let cameraPosition = GMSCameraPosition(target: lastLocation.coordinate, zoom: 15)
        mapView.animate(to: cameraPosition)
    }
}

Objective-C

#pragma mark - Create Buttons

- (NSArray<CPMapButton *>*)createMapButtons {
    NSMutableArray<CPMapButton *> *mapButtons = [NSMutableArray<CPMapButton *> array];

    __weak __typeof__(self) weakSelf = self;
    CPMapButton *panButton = [self mapButtonWithSystemImageNamed:@"dpad.fill"
                                                        handler:^(CPMapButton *_) {
                                                        [weakSelf didTapPanButton];
                                                        }];
    [mapButtons addObject:panButton];

    CPMapButton *zoomOutButton =
        [self mapButtonWithSystemImageNamed:@"minus.magnifyingglass"
                                    handler:^(CPMapButton *_Nonnull mapButon) {
                                    [weakSelf didTapZoomOutButton];
                                    }];
    [mapButtons addObject:zoomOutButton];

    CPMapButton *zoomInButton =
        [self mapButtonWithSystemImageNamed:@"plus.magnifyingglass"
                                    handler:^(CPMapButton *_Nonnull mapButon) {
                                    [weakSelf didTapZoomInButton];
                                    }];
    [mapButtons addObject:zoomInButton];

    CPMapButton *myLocationButton =
        [self mapButtonWithSystemImageNamed:@"location"
                                    handler:^(CPMapButton *_Nonnull mapButton) {
                                    [weakSelf didTapMyLocationButton];
                                    }];
    [mapButtons addObject:myLocationButton];
    return mapButtons;
}

#pragma mark - Button Callbacks

- (void)didTapZoomOutButton {
[_mapView animateWithCameraUpdate:[GMSCameraUpdate zoomOut]];
}

- (void)didTapZoomInButton {
[_mapView animateWithCameraUpdate:[GMSCameraUpdate zoomIn]];
}

- (void)didTapMyLocationButton {
CLLocation *location = self.lastLocation;
if (location) {
    GMSCameraPosition *position =
        [[GMSCameraPosition alloc] initWithTarget:self.lastLocation.coordinate zoom:15.];
    [_mapView animateToCameraPosition:position];
}
}

- (void)didTapPanButton {
[_mapTemplate showPanningInterfaceAnimated:YES];
_isPanningInterfaceEnabled = YES;
}

- (void)didTapStopPanningButton {
[_mapTemplate dismissPanningInterfaceAnimated:YES];
_isPanningInterfaceEnabled = NO;
}

ملاحظة: لا يمكن تحديد المسارات البديلة في شاشة CarPlay. يجب تحديدها من الهاتف قبل بدء CarPlay.

عرض اتجاهات التنقل

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

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

إعداد مستمع

اتّبِع تعليمات إعداد أداة معالجة الأحداث في تفعيل خلاصة البيانات المفصّلة.

تعبئة معلومات التنقّل

يعرض الجزء الأول من نموذج الرمز البرمجي التالي كيفية إنشاء تقديرات الرحلات على CarPlay من خلال ترجمة GMSNavigationNavInfo.timeToCurrentStepSeconds إلى CPTravelEstimate. يمكنك الاطّلاع على مزيد من المعلومات حول هذه العناصر وغيرها من عناصر العرض في تفعيل خلاصة البيانات المفصّلة.

يعرض الجزء الثاني من النموذج كيفية إنشاء عنصر وتخزينه في الحقل userInfo ضمن CPManuevers. يحدّد ذلك CPManeuverDisplayStyle الذي يُستخدم أيضًا للحصول على معلومات حول إرشادات الممرات. يمكنك الاطّلاع على دليل برمجة تطبيقات CarPlay من Apple للحصول على مزيد من المعلومات.

Swift

// Get a CPTravelEstimate from GMSNavigationNavInfo
func getTravelEstimates(from navInfo:GMSNavigationNavInfo) -> CPTravelEstimates {
    let distanceRemaining = navInfo.roundedDistance(navInfo.distanceToCurrentStepMeters)
    let timeRemaining = navInfo.roundedTime(navInfo.timeToCurrentStepSeconds)
    let travelEstimates = CPTravelEstimates(distanceRemaining: distanceRemaining, timeRemaining: timeRemaining)
    return travelEstimates
}

//  Create an object to be stored in the userInfo field of CPManeuver to determine the CPManeuverDisplayStyle. 

/** An object to be stored in the userInfo field of a CPManeuver. */

struct ManeuverUserInfo {
    var stepInfo: GMSNavigationStepInfo
    var isLaneGuidance: Bool
}

func mapTemplate(_ mapTemplate: CPMapTemplate, displayStyleFor maneuver: CPManeuver) -> CPManeuverDisplayStyle {
    let userInfo = maneuver.userInfo
    if let maneuverUserInfo = userInfo as? ManeuverUserInfo {
        return maneuverUserInfo.isLaneGuidance ? .symbolOnly : .leadingSymbol
    }
    return .leadingSymbol
}

// Get a CPManeuver with instructionVariants and symbolImage from GMSNavigationStepInfo
func getManeuver(for stepInfo: GMSNavigationStepInfo) -> CPManeuver {
    let maneuver = CPManeuver()
    maneuver.userInfo = ManeuverUserInfo(stepInfo: stepInfo, isLaneGuidance: false)
    switch stepInfo.maneuver {
        case .destination:
            maneuver.instructionVariants = ["Your destination is ahead."]
            break
        case .destinationLeft:
            maneuver.instructionVariants = ["Your destination is ahead on your left."]
            break
        case .destinationRight:
            maneuver.instructionVariants = ["Your destination is ahead on your right."]
            break
        default:
            maneuver.attributedInstructionVariants = currentNavInfo?.instructions(forStep: stepInfo, options: instructionOptions)
            break
    }
    maneuver.symbolImage = stepInfo.maneuverImage(with: instructionOptions.imageOptions)
    return maneuver
}

// Get the lane image for a CPManeuver from GMSNavigationStepInfo
func laneGuidanceManeuver(for stepInfo: GMSNavigationStepInfo) -> CPManeuver? {
    let maneuver = CPManeuver()
    maneuver.userInfo = ManeuverUserInfo(stepInfo: stepInfo, isLaneGuidance: true)
    let lanesImage = stepInfo.lanesImage(with: imageOptions)
    guard let lanesImage = lanesImage else { return nil }
    maneuver.symbolImage = lanesImage
    return maneuver
}

Objective-C

// Get a CPTravelEstimate from GMSNavigationNavInfo
- (nonull CPTravelEstimates *)travelEstimates:(GMSNavigationNavInfo *_Nonnull navInfo) {
NSMeasurement<NSUnitLength *> *distanceRemaining = [navInfo roundedDistance:navInfo.distanceToCurrentStepMeters];
NSTimeInterval timeRemaining = [navInfo roundedTime:navInfo.timeToCurrentStepSeconds];
CPTravelEstimate* travelEstimate = [[CPTravelEstimates alloc] initWithDistanceRemaining:distanceRemaining
                                                timeRemaining:timeRemaining];
}
//  Create an object to be stored in the userInfo field of CPManeuver to determine the CPManeuverDisplayStyle. 

/** An object to be stored in the userInfo field of a CPManeuver. */
@interface ManeuverUserInfo : NSObject

@property(nonatomic, readonly, nonnull) GMSNavigationStepInfo *stepInfo;
@property(nonatomic, readonly, getter=isLaneGuidance) BOOL laneGuidance;

- (nonnull instancetype)initWithStepInfo:(GMSNavigationStepInfo *)stepInfo
                        isLaneGuidance:(BOOL)isLaneGuidance NS_DESIGNATED_INITIALIZER;

- (instancetype)init NS_UNAVAILABLE;

@end

- (CPManeuverDisplayStyle)mapTemplate:(CPMapTemplate *)mapTemplate
            displayStyleForManeuver:(nonnull CPManeuver *)maneuver {
ManeuverUserInfo *userInfo = maneuver.userInfo;
return userInfo.laneGuidance ? CPManeuverDisplayStyleSymbolOnly : CPManeuverDisplayStyleDefault;
}
// Get a CPManeuver with instructionVariants and symbolImage from GMSNavigationStepInfo
- (nonnull CPManeuver *)maneuverForStep:(nonnull GMSNavigationStepInfo *)stepInfo {
CPManeuver *maneuver = [[CPManeuver alloc] init];
maneuver.userInfo = [[ManeuverUserInfo alloc] initWithStepInfo:stepInfo isLaneGuidance:NO];
switch (stepInfo.maneuver) {
    case GMSNavigationManeuverDestination:
    maneuver.instructionVariants = @[ @"Your destination is ahead." ];
    break;
    case GMSNavigationManeuverDestinationLeft:
    maneuver.instructionVariants = @[ @"Your destination is ahead on your left." ];
    break;
    case GMSNavigationManeuverDestinationRight:
    maneuver.instructionVariants = @[ @"Your destination is ahead on your right." ];
    break;
    default: {
    maneuver.attributedInstructionVariants =
        [_currentNavInfo instructionsForStep:stepInfo options:_instructionOptions];
    break;
    }
}
maneuver.symbolImage = [stepInfo maneuverImageWithOptions:_instructionOptions.imageOptions];
return maneuver;
}
// Get the lane image for a CPManeuver from GMSNavigationStepInfo
- (nullable CPManeuver *)laneGuidanceManeuverForStep:(nonnull GMSNavigationStepInfo *)stepInfo {
CPManeuver *maneuver = [[CPManeuver alloc] init];
maneuver.userInfo = [[ManeuverUserInfo alloc] initWithStepInfo:stepInfo isLaneGuidance:YES];
UIImage *lanesImage = [stepInfo lanesImageWithOptions:_imageOptions];
if (!lanesImage) {
    return nil;
}
maneuver.symbolImage = lanesImage;
return maneuver;
}

مناورات

تستخدم CarPlay فئة CPManeuver لتقديم إرشادات مفصّلة. يمكنك الاطلاع على تفعيل خلاصة البيانات المفصّلة للحصول على مزيد من المعلومات حول المناورات وإرشادات الممرات.

مستندات ذات صلة

• https://developer.apple.com/carplay/
• https://developer.apple.com/carplay/documentation/CarPlay-App-Programming-Guide.pdf
• https://developer.apple.com/design/human-interface-guidelines/carplay
• تفعيل خلاصة البيانات المفصّلة
• التنقُّل في مسار