by Derek Lu
Table of contents
15 July 2013
User level: Intermediate
Required Adobe products
Additional required other products
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
Note: If you have questions about this article, use the tutorial feedback link at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
There are many ways GPS data can be leveraged in a DPS application. The purpose of this article is to help you understand how to implement this capability and to help you understand some of the possibilities of what you can do with this new capability.
Some of the ways you could leverage a device’s location include,
- Deliver regional content within a folio; readers of a travel tips section of a magazine in the Northwest view an article about the Northwest, while readers located outside of the Northwest reading the same travel tips section see an article about Southern California.
- A magazine travel ad includes information highlighting a local travel agency; thus a reader in California sees one travel agency, while a reader in Nevada sees a different travel agency.
- Offer promotional content to attendees of a conference or sporting event.
- Readers on the west coast see a different list of folios than readers on the east coast.
In this article I’ll cover the first two use cases and provide an outline for implementing the final two.
The geolocation api returns a latitude and longitude which must be translated to a location. The process of converting a point (latitude, longitude) to an address is called reverse geocoding. Before using the geolocation api you must sign up for a reverse geocoding service such as Bing maps. Google maps also offers a reverse geocoding service but you must display their map in order to use it. The examples in this article do not display a map so Bing maps is used. You can sign up for an account at the Bing maps portal.
The Bing maps reverse geocode service works by passing it a latitude, longitude and key in the URL which returns either JSON or XML, ex:
The latitude/longitude passed through this example URL is the approximate location of Adobe headquarters in San Jose, CA. The key is a value provided by Bing after signing up for a developer account. If you click the URL you will see JSON returned that includes location data for the point such as address, locality, postal code and country.
The steps below outline how to get location data using the geolocation api.
- Obtain a Bing maps API key
- Set the minimum viewer and folio version to v27 in App Builder
- Check “Allow Access to Entitlement Information” in Folio Producer
adobeDPS.geolocation.getCurrentPosition()to get the latitude and longitude
- Call the Bing maps API to get the location data for your user
- Get the relevant location data from the Bing response
- Apply business logic that decides what content to show
The following sections describes each of the steps in more detail. A working example of these steps is in the attached sample files in basic/index.html. The sample outputs the values from
getCurrentPosition()and the address data of the Bing maps request.
Figure 1: The output from the basic/index.html
- Obtain a Bing maps API keyIf you have not already done so go to Bing maps and create a user account. After creating a user account go to “Create or view keys” from the left nav to create an API key. This key will be used in each request to the Bing maps API.
- Set the minimum viewer and folio version to v27In App Builder create a viewer that is v27. In Folio Builder, create a folio using v27.
- Check “Allow Access to Entitlement Information”In order to enable the reading API, which the geolocation api is a part of, HTML articles and webviews must have this checkbox selected. The checkbox is available from Folio Producer at the article level for an HTML article and from the Web Content overlay panel.
Figure 2: Checkbox that allows access to the Reading API from a folio
adobeDPS.geolocation.getCurrentPosition()to get the latitude and longitudeThis method is called on line 11 of the sample file. This method takes two parameters, a success callback function and an error callback function. The success callback is passed a position object that includes a coords property with the pro is passed an error object which includes the error code and description. The first time this method is called users will see a dialog asking for permission to get the current location. If users perties: latitude, longitude, accuracy, altitude, altitude accuracy, heading and speed. The values are retrieved beginning on line 15 of the sample. The error callback tap “Don’t Allow” the error callback is triggered. If the error callback is triggered you will want to display either default content or a message saying that location settings can be changed in the future by going to Settings > Privacy > Location Services > <app-name>
Figure 3: Dialog asking for permission to get the user’s current location
- Call the Bing API to get the location data for your userThe Bing API is called beginning on line 46 of the sample. To reverse geocode the user’s location using Bing maps, you need to construct a URL using the latitude and longitude from
getCurrentPosition()and the key from Bing maps. The URL is of the format:
http://dev.virtualearth.net/REST/v1/Locations<latitude>,<longitude>?key=<Bing-maps-api-key>The example files use jQuery to make an ajax request to get the data. The returned data is JSON.
- Get the relevant location data from the Bing responseThe data is retrieved beginning on line 51 of the sample. Using jQuery you can drill down to the address data by using
responseData.resourceSets.resources.address. This address object contains addressLine, city, postalCode, county, state and country. The values are retrieved beginning on line 52 of the sample.
- Apply business logic that decides which content to showUsing the address data returned by Bing maps, you can now apply your business logic to show custom content to your users. The following examples will show use cases on how this logic can be applied. Each example will use the same steps above but will have different business logic applied to display custom content.
This example illustrates how to display an article based on a user’s location. The sample files are in the “articles” directory. The implementation is done using an HTML article. When a user navigates to the page, if they are in Oregon or Washington they will see an article about the Northwest. If the user is not in either of the two states they will see an article about Southern California.
Figure 4: The Northwest article for readers in Washington or Oregon
Figure 5: The Southern California article for readers outside of Washington and Oregon
If you open articles/index.html you will see that getting the location data is the same as the steps above through step 6. The difference is on line 33 which contains the logic that determines which article to load. In this case we are simply redirecting to the appropriate article.
if (state.toLowerCase() == "wa" || state.toLowerCase() == "or") window.location = "articles/northwest.html"; else window.location = "articles/southern_ca.html";
This example illustrates how to display an ad based on a user’s location. The sample files are in the “ad” directory. This implementation is done using a web content overlay. When a user navigates to the page, if they are in California they will see one retailer and if they are outside of California they will see another retailer.
Figure 6: The travel agency displayed for users outside of California
Figure 7: The travel agency displayed for users in California
If you open ad/index.html you will see that getting the location data is the same as the steps above through step 6. After finding the state, an image for the travel agency is displayed depending on the location of the user. The difference between this example and the previous one, is this one is within a web view overlay and only changes part of the page. Beginning on line 33 you can see the condition that checks for whether or not the user is in California. Depending on the location the
<img>source is set for the respective image.
The scenario for this example would be to offer promotional content for users at a conference. This could be accomplished by either using an entitlement banner or a custom library/store but rather than the reading API, AdobeReadingAPI.js, you would use the library api, AdobeLibraryAPI.js. The geolocation API is available in both APIs but the reading API is used within a folio while the library API is used in the entitlement banner or a custom library/store. To implement this example one would follow the same steps above to get the location and then business logic would need to be implemented on the server to entitle the user to a folio based on their location.
The general steps would be:
- Get the user’s location.
- Have the user register by creating a username and password.
- Send the location and registration information to the server.
- On the server, figure out if the user is in the correct location to offer a promotional folio.
- On the server, entitle the user to the promotional folio.
- On the device, login the user so the entitlements are updated, which will include the promotional folio. Since the user is now entitled to the folio, if they subsequently leave the area and start the viewer they will still be entitled to the folio.
For more information on direct entitlement, go to Leveraging direct entitlement with Digital Publishing Suite.
The scenario for this example would be to offer a list of folios based on a user’s location. This would be accomplished by using a custom library/store which will allow you to control what a user can see. As in the example above, the library API, AdobeLibrary.js, is used. This use case follows the same steps above to get the location and then business logic would be implemented on the client to display the relevant folios. If you need a custom store to get started you can create one using the store configurator.
The general steps would be:
- Get the user’s location.
- Determine which region the user is in.In this use case if we assume users are either on the east coast or west coast, we could figure out the state a user is in and then determine which region we would like to put them in. For example, if a user is not in Washington, Oregon, California or Arizona, we can assume a user is on the east coast.
folio.productId.indexOf(“east”) > -1to filter folios for users on the east coast.
In this article you learned how to use the geolocation API. We are always interested to hear more about how customers are using the features like the geolocation API. So if you implement something interesting, tell us about it, and maybe we’ll showcase it on Adobe.com!
Also remember, when you are debugging your geolocation implementation and nothing is working be sure to double check that you have selected “Allow Access to Entitlement Information” in Folio Producer.
For more information on DPS, visit the DPS Developer Center.
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.