Mobile Platform as a Service:Integrate with iOS

Add the Location plugin to an existing iOS project using CocoaPods to access location-based services (LBS) APIs for retrieving device location data.

Use the SDK

The following examples are based on the official Location demo and apply to baseline 10.1.32 and later. The APMobileLBS module returns the device's current latitude and longitude.

API reference

Configure parameters with MPLBSConfiguration

/**
 Configuration for the location service.
 */
@interface MPLBSConfiguration : NSObject

/** The desired accuracy for a single location request, in meters. Pass an acceptable positive number based on your scenario, such as 500 for a 500 m range. */
@property (nonatomic, assign) CLLocationAccuracy desiredAccuracy;

/** The acceptable cache duration for a single location request. This value specifies how long a cached location is valid, measured back from the current time. Set the cache time to 30s or longer. */
@property (nonatomic, assign) APCoreLocationCacheAvaliable cacheTimeInterval;

/** The timeout period for a single location request or reverse geocoding query, in seconds. The default and minimum value is 2s. */
@property (nonatomic, assign) NSTimeInterval timeOut;

/** The information level for the reverse geocoding query. The default is APCoreLocationReGeoLevelDistrict. */
@property (nonatomic, assign) LBSLocationReGeoLevel reGeoLevel;

/** The location information for the reverse geocoding query. Specify the latitude and longitude coordinates in this parameter. */
@property (nonatomic, strong) CLLocation *reGeoLocation;

/** Specifies whether the location information for the reverse geocoding query uses the Amap coordinate system. The default is YES. This parameter takes effect only when the reGeoLocation parameter is used. */
@property (nonatomic, assign) BOOL reGeoCoordinateConverted;

/** Specifies whether to enable the check-in feature. The default is NO. Enable it as needed. */
@property (nonatomic, assign) BOOL needCheckIn;

/**
 *  Specifies whether high-accuracy location is required. iOS versions earlier than 14 do not differentiate accuracy. For iOS 14 and later, the default is NO (low accuracy). Specify whether your service requires high-accuracy location.
 */
@property (nonatomic,assign) BOOL highAccuracyRequired;

@end

Initiate a location request with MPLBSLocationManager

/**
 The callback block for the location result.

 @param success Specifies whether the operation was successful.
 @param locationInfo The location information.
 @param error The error message if the location request failed.
 */
typedef void(^MPLBSLocationCompletionBlock)(BOOL success,
                                            MPLBSLocationInfo *locationInfo,
                                            NSError *error);

/**
 The location service.
 */
@interface MPLBSLocationManager : NSObject

/**
 Initializes the instance.

 @param configuration The parameter settings.
 @return An instance.
 */
- (instancetype)initWithConfiguration:(MPLBSConfiguration *)configuration;

/**
 Initiates a single location request.

 @param needReGeocode Specifies whether reverse geocoding information is needed. Because the location service does not support reverse geocoding, pass NO for this parameter.
 @param block The callback block for when the location request is complete.
 */
- (void)requestLocationNeedReGeocode:(BOOL)needReGeocode
                   completionHandler:(MPLBSLocationCompletionBlock)block;

Description of MPLBSLocationInfo in the callback

/**
 Reverse geocoding information.
 */
@interface MPLBSReGeocodeInfo : NSObject

@property (nonatomic, strong) NSString* country;        // Country
@property (nonatomic, strong) NSString* countryCode;    // Country code
@property (nonatomic, strong) NSString* provience;      // Province
@property (nonatomic, strong) NSString* city;           // City
@property (nonatomic, strong) NSString* district;       // District
@property (nonatomic, strong) NSString* street;         // Street
@property (nonatomic, strong) NSString* streetCode;     // Street code
@property (nonatomic, strong) NSString* cityCode;       // City code
@property (nonatomic, strong) NSString* adCode;         // Administrative region code
@property (nonatomic, strong) NSArray* poiList;         // POI list

@end

/**
 The data structure for location information in the location result.
 */
@interface MPLBSLocationInfo : NSObject

@property (nonatomic, strong) CLLocation* location;         // Location information
@property (nonatomic, strong) MPLBSReGeocodeInfo* rgcInfo;  // Reverse geocoding information

@end

Code example

The example below retrieves the device location and displays the result — including coordinates, accuracy, and whether precise location is enabled.

- (void)getLocation {
    MPLBSConfiguration *configuration = [[MPLBSConfiguration alloc] init];
    configuration.desiredAccuracy = kCLLocationAccuracyBest;

    self.locationManager = [[MPLBSLocationManager alloc] initWithConfiguration:configuration];
    [self.locationManager requestLocationNeedReGeocode:NO completionHandler:^(BOOL success, MPLBSLocationInfo * _Nonnull locationInfo, NSError * _Nonnull error) {
        NSString *message;
        if (success) {
            message = [NSString stringWithFormat:@"Location successful. Longitude: %.5f, Latitude: %.5f, Accuracy: %.3f, High accuracy: %d", locationInfo.location.coordinate.longitude, locationInfo.location.coordinate.latitude, locationInfo.location.horizontalAccuracy, !locationInfo.location.ap_lbs_is_high_accuracy_close];
        } else {
            message = [NSString stringWithFormat:@"%@", error];
        }
        dispatch_async(dispatch_get_main_queue(), ^{
            AUNoticeDialog *alert = [[AUNoticeDialog alloc] initWithTitle:@"Location Result" message:message delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
            [alert show];
        });
    }];
}

iOS 14 adaptation

iOS 14 introduced Precise Location as a per-app permission. Users can toggle it when granting location access and later change it in Settings. The SDK handles both scenarios through the highAccuracyRequired parameter and the ap_lbs_is_high_accuracy_close field.

Input parameter adaptation

Set highAccuracyRequired in MPLBSConfiguration to declare whether your feature requires precise location. If you set highAccuracyRequired = YES but the user has not granted high-accuracy permission, the callback returns an error instead of a location result.

/**
 Configuration for the location service.
 */
@interface MPLBSConfiguration : NSObject

/**
 *  Specifies whether high-accuracy location is required. iOS versions earlier than 14 do not differentiate accuracy. For iOS 14 and later, the default is NO (low accuracy). Specify whether your service requires high-accuracy location.
 */
@property (nonatomic,assign) BOOL highAccuracyRequired;

@end

// If highAccuracyRequired is set to YES and high-accuracy location permission is not granted, an error is returned in the callback.
Errorcode: APCoreLocationErrorCodeHighAccuracyAuthorization

Callback adaptation

When highAccuracyRequired = NO (or the parameter is omitted), the callback succeeds regardless of the user's precision setting. The returned CLLocation object includes the ap_lbs_is_high_accuracy_close field, which your app can read to determine whether precise location was available.

// Response parameter modification
@interface CLLocation (APMobileLBS)
/*
 *  Specifies whether precise location is disabled. The default is NO.
 */
@property(nonatomic,assign)BOOL ap_lbs_is_high_accuracy_close;
@end

Code example

- (void)getLocationWithHighAccuracy {
    MPLBSConfiguration *configuration = [[MPLBSConfiguration alloc] init];
    configuration.desiredAccuracy = kCLLocationAccuracyBest;
    configuration.highAccuracyRequired = YES;

    self.locationManager = [[MPLBSLocationManager alloc] initWithConfiguration:configuration];
    [self.locationManager requestLocationNeedReGeocode:NO completionHandler:^(BOOL success, MPLBSLocationInfo * _Nonnull locationInfo, NSError * _Nonnull error) {
        NSString *message;
        if (success) {
            message = [NSString stringWithFormat:@"Location successful. Longitude: %.5f, Latitude: %.5f, Accuracy: %.3f, High accuracy: %d", locationInfo.location.coordinate.longitude, locationInfo.location.coordinate.latitude, locationInfo.location.horizontalAccuracy, !locationInfo.location.ap_lbs_is_high_accuracy_close];
        } else {
            message = [NSString stringWithFormat:@"%@", error];
        }
        dispatch_async(dispatch_get_main_queue(), ^{
            AUNoticeDialog *alert = [[AUNoticeDialog alloc] initWithTitle:@"Location Result" message:message delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
            [alert show];
        });
    }];
}