SDK Docs
Support

Additional Resources

Suggest Edits

Upgrade from a Previous SDK Version

🚧

The steps outlined on this page are only applicable if you installed the SDK prior to 2.1.0 with a .netrc file. For current installation steps, please refer to our getting started page.

As part of the Pilgrim 2.1.0 release we made it easier to get the SDK into your iOS project by allowing developers to download the framework through standard iOS dependency managers (Carthage, CocoaPods & manually). The changes to get the SDK integrated for each platform are outlined below:

Carthage

  1. Remove the Pilgrim credentials from the .netrc file.

CocoaPods

  1. Remove the Pilgrim credentials from the .netrc file.

  2. Remove reference to the old foursquare Artifactory repository by removing the following lines from the top of your Podfile.

foursquare-internal

  1. Run pod repo update to get the latest version of the CocoaPods Spec's repo (needed so that cocoapods is able to see the Pilgrim podspec)

  2. Install Pilgrim using the instructions outlined on our getting started page.

Note: if you are using any other SDK's installed using Artifactory, only remove the 'foursquare-internal' line.

Manual Installation

  1. Remove the Pilgrim credentials from the .netrc file.

iOS14+ Prep

With the release of iOS 14, Apple has made a few changes that may impact how you use the Pilgrim SDK. Specifically, the changes introduced are:

  • IDFA Permission
  • Updated Location Permission Prompts
  • Temporary Precise Location

Below you'll find some more information on the changes and how you should handle them in your app.

IDFA Permission

What’s New?

In the new IDFA flow, an app can request access to the IDFA via a prompt to the user. If the user opts to allow tracking, the app will be able to access the IDFA via the same property on the ASIdentifierManager Class as before. The user also has a global “Allow Apps to Request to Track” switch that they can toggle to suppress all IDFA prompts moving forward.

With the removal of the “Limit Ad Tracking” switch, Apple has also deprecated the isAdvertisingTrackingEnabled method which allowed developers to check if the IDFA was available to collect. Developers will now need to switch over to the new AppTrackingTransparency framework’s trackingAuthorizationStatus method to see the permission state of the IDFA. They will then use the requestTrackingAuthorization method to prompt for permission to collect the IDFA.

Requesting Access to the IDFA

To display the App Tracking Transparency authorization prompt for accessing the IDFA, you'll first need to update your Info.plist file to add the NSUserTrackingUsageDescription key - as well as a message describing why you need access to the IDFA.

<key>NSUserTrackingUsageDescription</key>
<string>This Id helps us serve relevant ads that are tailored to you</string>

To present the authorization prompt, call requestTrackingAuthorizationWithCompletionHandler: and handle the authorization status

The prompt, along with your usage description, will appear as shown below:

Updated Location Permission Prompts

What’s New?

iOS 14 introduces an updated permission prompt which includes a map and an additional toggle in the top left-hand corner of the map. This toggle allows users to turn on or off the “Precise Location” authorization. When switching between the two, the user is presented with two different maps. When the toggle is “ON,” the map shows the user’s exact location via the traditional “blue dot.” When the toggle is “OFF,” the map shows a zoomed-out view with a larger circle spanning a few miles surrounding the user.

Checking Location Authorization

What’s New?

In order to identify that a location is approximate, Apple has introduced an accuracyAuthorization property on the CLLocationManager that contains two states which identify whether your app has either reducedAccuracy or fullAccuracy permission enabled. The below screenshot shows how to handle either state;

Temporary Precise Location

What’s New?

Apple has also introduced a requestTemporaryFullAccuracyAuthorization method. This can be used when the user has opted out or denied "Precise Location". In addition to being able to request temporary access to precise location, you can add a custom "purpose string" that allows you to further surface why Precise Location is necessary.

More info

For a more in depth take on iOS 14 and it's changes with respect to the Pilgrim SDK, check out this blog post.

Updated 8 months ago