[ios, macos] document custom API URL & add Info.plist guide (#6833)

Also support base URL nullability in order to use default value.
mapbox · Nov 1, 2016 · 8ffd1f6 · 8ffd1f6
1 parent 300720c
commit 8ffd1f6
Show file tree

Hide file tree

Showing 7 changed files with 56 additions and 2 deletions.
diff --git a/platform/darwin/src/MGLNetworkConfiguration.h b/platform/darwin/src/MGLNetworkConfiguration.h
@@ -1,11 +1,23 @@
 #import <Foundation/Foundation.h>
 
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ The MGLNetworkConfiguration object provides a global way to set a base API URL for 
+ retrieval of map data, styles, and other resources.
+ 
+ Currently, MGLNetworkConfiguration is private API in code but is able to be used 
+ by any applications via the `MGLMapboxAPIBaseURL` dictionary key in the 
+ application's `Info.plist`.
+ */
 @interface MGLNetworkConfiguration : NSObject
 
 /// Returns the shared instance of the `MGLNetworkConfiguration` class.
 + (instancetype)sharedManager;
 
-/// The current API base URL.
-@property (atomic) NSURL *apiBaseURL;
+/// The current API base URL. If `nil`, the Mapbox default base API URL is in use. 
+@property (atomic, nullable) NSURL *apiBaseURL;
 
 @end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
@@ -65,6 +65,7 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 * Fixed a crash that occurred when encountering a rate-limit error in response to a network request. ([#6223](https://github.com/mapbox/mapbox-gl-native/pull/6223))
 * Fixed an issue causing an MGLOfflinePack’s progress to continue to update after calling `-suspend`. ([#6186](https://github.com/mapbox/mapbox-gl-native/pull/6186))
 * Fixed an issue preventing cached annotation images from displaying while the device is offline. ([#6358](https://github.com/mapbox/mapbox-gl-native/pull/6358))
+* Added support for an `MGLMapboxAPIBaseURL` key in an app's `Info.plist` in order to customize the base URL used for retrieving map data, styles, and other resources. ([#6709](https://github.com/mapbox/mapbox-gl-native/pull/6709))
 * Query parameters are no longer stripped from mapbox: URLs used as resource URLs. ([#6182](https://github.com/mapbox/mapbox-gl-native/pull/6182), [#6432](https://github.com/mapbox/mapbox-gl-native/pull/6432))
 * Database errors are now logged to the console. ([#6291](https://github.com/mapbox/mapbox-gl-native/pull/6291))
 

diff --git a/platform/ios/docs/Info.plist Keys.md b/platform/ios/docs/Info.plist Keys.md
@@ -0,0 +1,21 @@
+# Info.plist Keys
+
+The Mapbox iOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. 
+
+## MGLMapboxAccessToken
+
+Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/) to be used by all instances of `MGLMapView` in the current application.
+
+Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission.
+
+As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. 
+
+## MGLMapboxAPIBaseURL
+
+Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. 
+
+The default value is `https://api.mapbox.com`. 
+
+## MGLMapboxMetricsEnabledSettingShownInApp
+
+If you have implemented custom opt-out of Mapbox Telemetry within the user interface of your app, use this key to disable the built-in check for opt-out support. See [this guide](https://www.mapbox.com/ios-sdk/#telemetry_opt_out) for more details.
diff --git a/platform/ios/scripts/document.sh b/platform/ios/scripts/document.sh
@@ -38,6 +38,7 @@ jazzy \
  --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
  --module-version ${SHORT_VERSION} \
  --readme ${README} \
+ --documentation="platform/ios/docs/Info.plist Keys.md" \
  --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \
  --theme platform/darwin/docs/theme \
  --output ${OUTPUT}

diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
@@ -42,6 +42,7 @@
 * Fixed an issue preventing cached annotation images from displaying while the device is offline. ([#6358](https://github.com/mapbox/mapbox-gl-native/pull/6358))
 * Fixed a crash that could occur when the device is disconnected while downloading an offline pack. ([#6293](https://github.com/mapbox/mapbox-gl-native/pull/6293))
 * Fixed a crash that occurred when encountering a rate-limit error in response to a network request. ([#6223](https://github.com/mapbox/mapbox-gl-native/pull/6223))
+* Added support for an `MGLMapboxAPIBaseURL` key in an app's `Info.plist` in order to customize the base URL used for retrieving map data, styles, and other resources. ([#6709](https://github.com/mapbox/mapbox-gl-native/pull/6709))
 * Query parameters are no longer stripped from mapbox: URLs used as resource URLs. ([#6182](https://github.com/mapbox/mapbox-gl-native/pull/6182), [#6432](https://github.com/mapbox/mapbox-gl-native/pull/6432))
 * Database errors are now logged to the console. ([#6291](https://github.com/mapbox/mapbox-gl-native/pull/6291))
 

diff --git a/platform/macos/docs/Info.plist Keys.md b/platform/macos/docs/Info.plist Keys.md
@@ -0,0 +1,17 @@
+# Info.plist Keys
+
+The Mapbox macOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. 
+
+## MGLMapboxAccessToken
+
+Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/) to be used by all instances of `MGLMapView` in the current application.
+
+Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission.
+
+As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. 
+
+## MGLMapboxAPIBaseURL
+
+Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. 
+
+The default value is `https://api.mapbox.com`. 
diff --git a/platform/macos/scripts/document.sh b/platform/macos/scripts/document.sh
@@ -38,6 +38,7 @@ jazzy \
  --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
  --module-version ${SHORT_VERSION} \
  --readme ${README} \
+ --documentation="platform/macos/docs/Info.plist Keys.md" \
  --theme platform/darwin/docs/theme \
  --output ${OUTPUT}
 # https://github.com/realm/jazzy/issues/411