Show Menu
TOPICS×

Places extension

The Places extension allows you to act based on the location of your users. This extension is the interface to the Places Query Service APIs. By listening for events that contain GPS coordinates and geofence region events, this extension dispatches new events that are processed by the Rules Engine. The Places extension also retrieves and delivers a list of the nearest POI for the app data that retrieves from the APIs. The regions returned by the APIs are stored in cache and persistence, which allows limited offline processing.

Install the Places extension in Adobe Experience Platform Launch

  1. In Experience Platform Launch, click the Extensions tab.
  2. On the Catalog tab, locate the Places extension, and click Install .
  3. Select the Places libraries you want to use in this property. These are the libraries that will be accessible in your app.
  4. Click Save .
    When you click Save , the Experience Platform SDK searches the Places Services for POIs in the libraries that you selected. The POI data is not included in the download of the library when you build the app, but a location-based subset of POIs is downloaded to the end user's device at runtime and is based on the user's GPS coordinates.
  5. Complete the publishing process to update the SDK configuration.
    For more information about publishing in Experience Platform Launch, see Publishing .

Configure the Places extension

Add the Places extension to your app

You can add the Places extension to your Android and iOS apps.

Android

To add the Places extension to your app by using Java:
  1. Add the Places extension to your project using your app's gradle file.
    implementation 'com.adobe.marketing.mobile:places:1.+'
    implementation 'com.adobe.marketing.mobile:sdk-core:1.+'
    
    
  2. Import the Places extension in your application's main activity.
    import com.adobe.marketing.mobile.Places;
    
    

iOS

To add Places extension to your app by using Objective-C or Swift:
  1. Add the Places and Mobile Core libraries to your project. You will need to add the following pods to your Podfile :
    pod 'ACPPlaces', '~> 1.0'
    pod 'ACPCore', '~> 2.0'    # minimum Core version for Places is 2.0.3
    
    
    Alternatively, if you are not using Cocoapods, you can manually include the Mobile Core and the Places libraries from our releases page on Github.
  2. Update your Cocoapods:
    pod update
    
    
  3. Open Xcode, and in your AppDelegate class, import the Core and the Places headers:
    Objective-C
    #import "ACPCore.h"
    #import "ACPPlaces.h"
    
    
    Swift
    import ACPCore
    import ACPPlaces
    
    

Register the Places extension with Mobile Core

You need to register the Places extension with Mobile Core in Android and iOS.

Android

In your App's OnCreate method register the Places extensions:
public class PlacesTestApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        MobileCore.setApplication(this);

        try {
            Places.registerExtension();
            MobileCore.start(null);
        } catch (Exception e) {
            Log.e("PlacesTestApp", e.getMessage());
        }
    }
}

iOS

In your App's application:didFinishLaunchingWithOptions: method, register the Places extension with your other SDK registration calls:
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // make other sdk registration calls
    [ACPPlaces registerExtension];    
    return YES;
}

Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // make other sdk registration calls
    ACPPlaces.registerExtension();
    return true;
}

Modifying Places membership time-to-live

Location data can quickly become stale, especially if the device is not receiving background location updates.
Control the time-to-live for Places membership data on the device by setting the places.membershipttl configuration setting. The value passed in represents the number of seconds that the Places state will remain valid for the device.

Android

Inside the callback of MobileCore.start() update the configuration with the necessary changes prior to calling lifecycleStart :
public class PlacesTestApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        MobileCore.setApplication(this);

        try {
            Places.registerExtension();
            MobileCore.start(new AdobeCallback() {
                @Override
                public void call(Object o) {
                    // switch to your App ID from Launch
                    MobileCore.configureWithAppID("my-app-id");

                    final Map<String, Object> config = new HashMap<>();
                    config.put("places.membershipttl", 30);
                    MobileCore.updateConfiguration(config);

                    MobileCore.lifecycleStart(null);
                }
            });
        } catch (Exception e) {
            Log.e("PlacesTestApp", e.getMessage());
        }
    }
}

iOS

On the first line in the callback of ACPCore 's start: method, call updateConfiguration:
Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // make other sdk registration calls

    const UIApplicationState appState = application.applicationState;
    [ACPCore start:^{
        [ACPCore updateConfiguration:@{@"places.membershipttl":@(30)}];

        if (appState != UIApplicationStateBackground) {
            [ACPCore lifecycleStart:nil];            
        }
    }];

    return YES;
}

Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // make other sdk registration calls

    let appState = application.applicationState;            
    ACPCore.start {
        ACPCore.updateConfiguration(["places.membershipttl" : 30])

        if appState != .background {
            ACPCore.lifecycleStart(nil)
        }    
    }

    return true;
}

Configuration keys

To update the SDK configuration programmatically at runtime, use the following information to change your Places extension configuration values. For more information, see Configuration API Reference .
Key
Required
Description
places.libraries
Yes
The Places extension libraries for the mobile app. It specifies the library ID and the name of the library that the mobile app supports.
places.endpoint
Yes
The default Places Query Service endpoint, which is used to get information about libraries and POIs.
places.membershipttl
No
Default value of 3600 (seconds in an hour). Indicates how long, in seconds, Places membership information for the device will remain valid.