Prerequisite knowledge
Experience working with the Adobe Digital Publishing Suite (DPS), HTML and JavaScript is required. In addition, familiarity with the DPS Reading API will be useful.
 
User level: Intermediate
Required Adobe products
Additional required other products
Sample files
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
 

 
Introduction

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.
 
With release 27 of DPS (July 2013), customers can leverage the GPS on an iOS device to deliver richer experiences to their readers by delivering location specific content. This applies to both iPads and iPhones. The access to this information is done via JavaScript and can be used anywhere in a DPS app where HTML is used (e.g., Custom Store/Library, HTML Banner, HTML elements within a Folio).
 
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.
It’s important to remember, that this capability is accessed via a JavaScript API, which means your content will need to be in either an HTML article, webview overlay or a custom store/library, anywhere you have access to HTML in DPS.
 
In this article I’ll cover the first two use cases and provide an outline for implementing the final two.
 

 
Reverse geocode service

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.
 

 
How to get the location data

The steps below outline how to get location data using the geolocation api.
  1. Obtain a Bing maps API key
  2. Set the minimum viewer and folio version to v27 in App Builder
  3. Check “Allow Access to Entitlement Information” in Folio Producer
  4. Call adobeDPS.geolocation.getCurrentPosition() to get the latitude and longitude
  5. Call the Bing maps API to get the location data for your user
  6. Get the relevant location data from the Bing response
  7. 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
Figure 1: The output from the basic/index.html
 
 
  1. Obtain a Bing maps API key
    If 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.
  2. Set the minimum viewer and folio version to v27
    In App Builder create a viewer that is v27. In Folio Builder, create a folio using v27.
  3. 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
Figure 2: Checkbox that allows access to the Reading API from a folio
 
  1. Call adobeDPS.geolocation.getCurrentPosition() to get the latitude and longitude
    This 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
Figure 3: Dialog asking for permission to get the user’s current location
 
  1. Call the Bing API to get the location data for your user
    The 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.
  2. Get the relevant location data from the Bing response
    The data is retrieved beginning on line 51 of the sample. Using jQuery you can drill down to the address data by using responseData.resourceSets[0].resources[0].address. This address object contains addressLine, city, postalCode, county, state and country. The values are retrieved beginning on line 52 of the sample.
  3. Apply business logic that decides which content to show
    Using 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.
 

 
Location aware article serving

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 4: The Northwest article for readers in Washington or Oregon
 
Figure 5: The Southern California article for readers outside of Washington and 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";
When using window.location to redirect the page there is unfortunately a bug with the viewer in which it is not possible for a user to display the HUD by tapping the page from redirected pages. The user can however still navigate left and right to go to adjoining articles. If you would like users to be able to access the HUD, one workaround is to include the content from both articles in index.html. Using this method you could set display:none for the article that you would like to hide. Another alternative is to use JavaScript to output the article you would like to display. If you were using jQuery you could add the article using $(“body”).append().
 

 
Custom ad

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 6: The travel agency displayed for users outside of California
 
 
Figure 7: The travel agency displayed for users in 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.
 

 
Promotional content for users at a conference

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:
  1. Get the user’s location.
  2. Have the user register by creating a username and password.
  3. Send the location and registration information to the server.
  4. On the server, figure out if the user is in the correct location to offer a promotional folio.
  5. On the server, entitle the user to the promotional folio.
  6. 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.
 

 
Displaying folios based on a user’s location

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:
  1. Get the user’s location.
  2. 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.
  3. Add a condition to only display folios that are in a user’s region.
    One approach to designating folios for a particular region would be to use a common naming convention in the product id. For example, you could use com.adobe.inspire.east.june2013 and com.adobe.inspire.west.june2013 to delineate between the east and west coast. In your JavaScript you could then add a condition to check for folio.productId.indexOf(“east”) > -1 to filter folios for users on the east coast.
 

 
Where to go from here

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.