ÃÛ¶¹ÊÓƵ

DocumentationExperience PlatformMobile App Tutorial

Use Places

Last update: Tue Dec 05 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Intermediate
  • Developer

Learn how to use the Places geolocation service in your app.

The ÃÛ¶¹ÊÓƵ Experience Platform Data Collection Places Service is a geolocation service that enables mobile apps with location awareness to understand the location context. The service is using rich and easy-to-use SDK interfaces accompanied by a flexible database of points of interests (POIs).

Prerequisites

  • All package dependencies are in place in the Xcode project.
  • Registered extensions in AppDelegate.
  • Configured MobileCore to use your development appId.
  • Imported SDKs.
  • Successfully built and run the app with the above changes.

Learning objectives

In this lesson, you will

  • Understand how to define points of interest in the Places service.
  • Update your tag property with the Places extension.
  • Update your schema to capture geolocation events.
  • Validate setup in Assurance.
  • Update your app to register the Places extension.
  • Implement geolocation tracking from the Places service in your app.

Setup

For the Places service to work within your app and within the Mobile SDK, you have to do some setup.

Define Places

You define some points of interest in the Places service.

  1. In the Data Collection UI, select Places.
  2. Select More .
  3. From the context menu, select Manage Libraries.
    Manage libraries
  4. In the Manage Libraries dialog, select New.
  5. In the Create Library dialog enter a Name, for example Luma.
  6. Select Confirm.
    Create library
  7. To close the Manage Libraries dialog, select Close.
  8. Back in POI Management, select Import POIs.
  9. Select Start in the Import Places dialog.
  10. Select Luma from the list of libraries,
  11. Select Next.
    Select Library
  12. Download the Luma POIs ZIP file and extract it to a location on your computer.
  13. In the Import Places dialog, drag and drop the extracted luma_pois.csv file on to Choose CSV File - Drag and Drop your File. You should see Validation Success - Successfully validated the CSV file.
  14. Select Begin Import. You should see Success - Successfully added 6 new POIs.
  15. Select Done.
  16. In POI Management, you should see that six new Luma stores are added to the list. You can toggle between List list and Map map view.
    Places list .

Install Places extension

  1. Navigate to Tags and find your mobile tag property and open the property.

  2. Select Extensions.

  3. Select Catalog.

  4. Search for the Places extension.

  5. Install the extension.

    Add Decisioning extension

  6. In the Install Extension dialog:

    1. Select Luma from the Select a Library list.
    2. Ensure you have picked your working library, for example Initial Build.
    3. Select Save to Library and Build from Save to Library.
      Install Places extension .

  7. Your library is rebuilt.

Verify your schema

Verify whether your schema, as defined in Create schema, incorporates the necessary field groups and classes to collect POI and geolocation data.

  1. Navigate to Data Collection interface and select Schemas from the left rail.
  2. Select Browse from the top bar.
  3. Select your schema to open it.
  4. In the schema editor, select Consumer Experience Event.
  5. You see a placeContext object with object and fields to capture POI interaction and geolocation data.
    Schema Places .

Update your tag property

The Places extension for Tags provides functionality to monitor geolocation events and allows you to trigger actions based on these events. You can use this functionality to minimize the API coding you have to implement in the app.

Data Elements

You first create several data elements.

  1. Go to your tag property in the Data Collection UI.

  2. Select Data Elements from the left rail.

  3. Select Add Data Element.

  4. In the Create Data Element screen, enter a name, for example Name - Entered.

  5. Select Places from the Extension list.

  6. Select Name from the Data Element Type list.

  7. Select Current POI underneath TARGET.

  8. Select Save to Library.
    Data element

  9. Repeat steps 4 - 8 using the information from the table below, to create additional data elements.

    table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 5-row-4
    Name Extension Data Element Type TARGET
    Name - Exited Places Name Last Exited POI
    Category - Current Places Category Current POI
    Category - Exited Places Category Last Exited POI
    City - Current Places City Current POI
    City - Exited Places City Last Exited POI

    You should have the following list of Data Elements.

    List of data elements

Rules

Next, you are going to define rules to work with these data elements.

  1. In your tag property, select Rules from the left rail.

  2. Select Add Rule.

  3. In the Create Rule screen, enter a name for the rule, for example POI - Entry.

  4. Select Add underneath EVENTS.

    1. Select Places from the Extension list and select Enter POI from the Event Type list.
    2. Select Keep Changes.
      Tag event .

  5. Select Add underneath ACTIONS.

    1. Select Mobile Core from the Extension list, select Attach Data from Action Type the list. This action attaches payload data.

    2. In the JSON Payload, paste the following payload:

      code language-json 
      {
    "xdm": {
        "eventType": "location.entry",
        "placeContext": {
            "geo": {
                "city": "{%%City - Current%%}"
            },
            "POIinteraction": {
                "poiDetail": {
                    "name": "{%%Name - Current%%}",
                    "category": "{%%Category - Current%%}"
                },
                "poiEntries": {
                    "value": 1
                }
            }
        }
    }
}

      You can also insert {%% ... %%} data element placeholder values in the JSON by selecting the Data . A popup dialog allows you to pick any data element you created.

    3. Select Keep Changes.
      Tags action

  6. Select Add next to the Mobile Core - Attach Data action.

    1. Select ÃÛ¶¹ÊÓƵ Experience Platform Edge Network from the Extension list and select Forward event to Edge Network. This action ensures that the event and additional payload data are forwarded to Platform Edge Network.
    2. Select Keep Changes.

  7. To save the rule, select Save to Library.

    Rule

Let’s create another rule

  1. In the Create Rule screen, enter a name for the rule, for example POI - Exit.

  2. Select Add underneath EVENTS.

    1. Select Places from the Extension list and select Exit POI from the Event Type list.
    2. Select Keep Changes.

  3. Select Add underneath ACTIONS.

    1. Select Mobile Core from Extension list, select Attach Data from Action Type list.

    2. In the JSON Payload, paste the following payload:

      code language-json 
      {
    "xdm": {
        "eventType": "location.exit",
        "placeContext": {
            "geo": {
                "city": "{%%City - Exited%%}"
            },
            "POIinteraction": {
                "poiExits": {
                    "value": 1
                },
                "poiDetail": {
                    "name": "{%%Name - Exited%%}",
                    "category": "{%%Category - Exited%%}"
                }
            }
        }
    }
}

    3. Select Keep Changes.

  4. Select Add next to the Mobile Core - Attach Data action.

    1. Select ÃÛ¶¹ÊÓƵ Experience Platform Edge Network from the Extension list and select Forward event to Edge Network.
    2. Select Keep Changes.

  5. To save the rule, select Save to Library.

    Rule

To ensure all changes in your tag are published

  1. Select Initial Build as the library to build.
  2. Select Build.
    Build library

Validate setup in Assurance

To validate your setup in Assurance:

  1. Go to the Assurance UI.
  2. If not already available in the left rail, select Configure in left rail and select Add next to Events and Map & Simulate underneath PLACES SERVICE.
  3. Select Save.
  4. Select Map & Simulate in the left rail.
  5. Move the map to a location of one of your POI’s.
  6. Select Gear Simulate Load POIs. Your POI is identified using a circle and pin.
  7. Select your POI.
  8. From the popup, select Gear Simulate Entry Event.
    Simulate Entry Event
  9. Select Events from the left rail, and you should see the events that you simulated.
    AJO Decisioning validation

Implement Places in your app

As discussed in previous lessons, installing a mobile tag extension only provides the configuration. Next you must install and register the Places SDK. If these steps aren’t clear, review the Install SDKs section.

NOTE
If you completed the Install SDKs section, then the Places SDK is already installed and you can skip this step.

  1. In Xcode, ensure that is added to the list of packages in Package Dependencies. See Swift Package Manager.

  2. Navigate to Luma > Luma > AppDelegate in the Xcode Project navigator.

  3. Ensure AEPPlaces is part of your list of imports.

    code language-swift 
    import AEPPlaces

  4. Ensure Places.self is part of the array of extensions that you are registering.

    code language-swift 
    let extensions = [
    AEPIdentity.Identity.self,
    Lifecycle.self,
    Signal.self,
    Edge.self,
    AEPEdgeIdentity.Identity.self,
    Consent.self,
    UserProfile.self,
    Places.self,
    Messaging.self,
    Optimize.self,
    Assurance.self
]

  5. Navigate to Luma > Luma > Utils > MobileSDK in the Xcode Project navigator and find the func processRegionEvent(regionEvent: PlacesRegionEvent, forRegion region: CLRegion) async function. Add the following code:

    code language-swift 
    // Process geolocation event
Places.processRegionEvent(regionEvent, forRegion: region)

    This API communicates the geolocation information to the Places service.

  6. Navigate to Luma > Luma > Views > Location > GeofenceSheet in Xcode’s Project navigator.

    1. For the Entry button, enter the following code
    code language-swift 
    // Simulate geofence entry event
Task {
    await MobileSDK.shared.processRegionEvent(regionEvent: .entry, forRegion: region)
}
    1. For the Exit button, enter the following code
    code language-swift 
    // Simulate geofence exit event
Task {
    await MobileSDK.shared.processRegionEvent(regionEvent: .exit, forRegion: region)
}

Validate using your app

  1. Open your app on a device or in the simulator.

  2. Go to the Location tab.

  3. Move (drag) the map around to ensure that the blue middle circle is on above of one of your POI’s, for example London.

  4. Tap {width="20/"} until you see the category and name appear in the label at the red location with the pin.

  5. Tap the label of the POI, which opens up the Nearby POI sheet.

    {width="300/"}

  6. Press the Entry or Exit buttons to simulate geofence entry and geofence exit events from the app.

    {width="300/"}

  7. You should see the events in the Assurance UI.

Next steps

You should now have all the tools to start adding more functionality to your geolocation functionality in the app. As you have forwarded the events to the Edge Network, once you have set up the app for Experience Platform, you should see the experience events appearing for the profile used in the app.

In the Journey Optimizer section of this tutorial, you will see that experience events can be used to trigger journeys (see push notification and in-app messaging with Journey Optimizer). For example, the usual example of sending your app user a push notification with some product promotion when that user enters the geofence of a physical store.

You have seen an implementation of functionality for your app, mostly driven by the Places service and data elements and rules you defined in your tag property. As such, minimizing the code in your app. Alternatively, you can implement the same functionality directly in your app using the API (see Events for more information) with an XDM payload containing a populated placeContext object.

SUCCESS
You have now enabled the app for geolocation services using the Places extension in the Experience Platform Mobile SDK.
Thank you for investing your time in learning about ÃÛ¶¹ÊÓƵ Experience Platform Mobile SDK. If you have questions, want to share general feedback, or have suggestions on future content, share them on this .

Next: Map data to ÃÛ¶¹ÊÓƵ Analytics

recommendation-more-help
9fed61f5-c338-47ad-8005-0b89a5f4af8b