Before Starting

Make sure you have configured your beacon using the Eddystone Protocol, with a Namespace and an Instance. You can learn about naming beacons in the blog here: https://revolution11blog.com/2019/05/01/beacon-naming-standards/

Your beacon manufacturer should have provided instructions about setting up your beacon.  Here are some sample instructions we have written about configuring Minew Beacons: https://revolution11blog.com/2019/04/30/basic-configuration-of-minew-beacons/

You will also want to make sure and get the Latitude and Longitude of the location where you will be placing the beacon.

Determining Your Latitude and Longitude

Open up Google maps and find your current location. Right click on the location on the map and choose “What’s Here?” You will get a popup containing the latitude and longitude, go ahead and make note of them.

Determine the PlaceID

Google’s PlaceID is used with the Places API. 

Go to https://developers.google.com/places/place-id and find your location. Make note of the PlaceID.

Enabling the Proximity API

1.  Go to https://console.developers.google.com/apis/library/proximitybeacon.googleapis.com and log in as the root user.
2. Select the Project you would like to use with the Proximity API.
3. Press “Enable”.

Create Credentials

1.  Once the API Setup is complete you will land on the Manage API page. You’ll see we need to create credentials.  Click on credentials in the bar to the left.

2.  On the credentials home page, we’ll start by configuring the consent screen that pops up when this API is called. Press the Configure Consent Screen button.

3.  We’re going to do a minimum configuration to get us going. We’ll name our app Beacon App and upload an icon for it to use for the application logo.

4.  Scroll down and press “Save”.

5.  On the next screen click on create credentials and choose OAuth client ID.

6.  Select Web Application and press “Create”.

7.  Name the credentials and paste the URL for google’s OAuth Playground (https://developers.google.com/oauthplayground/) in the Authorized redirect URLs field. This allows us to test adding beacons to the beacon dashboard. Press “Create”.

8.  You should get a pop-up with the Client ID and Secret we will be using in the OAuth Playground. Copy the Client ID then click “OK”.

Testing the Proximity API with the OAuth Playground

1. Open Google’s OAuth Playground in a new browser window with this URL: ​developers.google.com/oauthplayground

2.  Click the gear icon in the top right corner and:
● Change “OAuth flow” to “Client-side”.
● Check the “Use your own OAuth credentials” checkbox.
● Paste the client ID you generated in the previous step, click on close.

3.  Then, on the left side, in the “Input your own scopes” text field, type:

https://www.googleapis.com/auth/userlocation.beacon.registry and press the authorize APIs button.

4.  You will be asked to sign in.

5.  You will be asked to give permission to view and modify the beacons. Click on “Allow.”

6.  You will be asked to confirm your choices. Press “Allow.” 

Creating an AdvertisingID

1.  Now we need to create an AdvertisingID to use with the Proximity API. This is made with a packing function using the Namespace and Instance that the beacon is using.  There are a lot of ways to do this within an app, but since we are in the Google OAuth playground, and we are working with a Mac, we are going to do this really quickly in ruby with the terminal app. Open the terminal app from apps/utilities and fire up the ruby application by typing irb and then hit return.

2.  Type in the following using your Namespace and Instance in the terminal and hit return.

require ‘base64’
namespace = ‘YourNameSpaceHere’
instance = ‘YourInstanceHere
puts Base64.strict_encode64([namespace + instance].pack(‘H*’))

This will generate the AdvertisingID as shown below:

Registering the Beacon

1. Now return to the OAuth playground.

• For “HTTP Method” pick “POST.” For “Request URI” enter: https://proximitybeacon.googleapis.com/v1beta1/beacons:register
• Press “Enter Request Body”

2.  Below is an example you can paste in, replace the example data with your own.

• The advertisingID you generated in the terminal
• The place ID you copied earlier
• The latitude and longitude you collected earlier
• The Places API supports floors for indoor mapping so we are going to set the name of the indoor level to 1 in our example
• You can add a description of the beacon here
• And in the properties, you can add any key value pairs you wish, we are starting with the key of position and the value of entryway.

Once the request URI text is entered press “Close”

3.  Hit “Send the Request”.

4.  You should see a successful post message.

View the Beacon on Google’s Beacon Dashboard

1.  Go to https://developers.google.com/beacons/dashboard/  Since this is the first time you have used the beacon dashboard, you will get a pop-up message. Press “Start”.

2.  Another pop-up will appear asking for permission to use your account, click on “Allow”.

3.  Choose the project you are using with the Proximity API.

4.  You should land on summary page of the beacons connected to that project.  Congratulations, you have successfully setup the proximity API! The developer you set up in the last blog should now be able to work with the API.