The easiest way to add Nearby Notifications attachments is though the Google Beacon Dashboard. Alternatively, you may use the Proximity Beacon API and the attachment data format described below.
Attachments for the Nearby Notifications feature must use the
com.google.nearby namespace, and a type consisting of the two-letter language
code, and optional -debug suffix.
Attachments should be formatted using JSON. For example:
{
"title": "Example",
"url": "https://www.example.com"
}
The JSON format optionally allows for more specific targeting as shown below:
{
"title": "Example",
"url": "https://www.example.com",
"targeting":[
{
"startDate": "2017-01-01",
"endDate": "2017-01-31",
"startTimeOfDay": "9:00",
"endTimeOfDay": "17:00",
"anyOfDaysOfWeek": [1, 2, 3, 4, 5, 6, 7],
"anyOfAppInstallStates": ["INSTALLED", "NOT_INSTALLED"]
}
]
}
Where:
- title — Title of the content. The length of
titleshould be less than 40 characters and must be less than 50 characters. This should ideally give the user a call to action. For example,Order with your phone, skip the line,Set up your thermostat, orLearn more about sea otters. - url — The URL for the app, website, or service.
- targeting — Optional rules for limiting notification visibility based on device context.
URL formats
Nearby Notifications supports three URL formats:
Web URL
A web URL is exactly that, just a normal URL. When a web URL is received, the user is prompted to open the URL in the default browser. No special app configuration is required. Web URLs must use HTTPS, and are formatted as a normal URL:
https://www.example.com
If your web URL isn't triggering a notification the most likely causes are:
- Using HTTP instead of HTTPS
- Linking to app store such as play.google.com is prohibited. The web page should stand on it's own and offer useful information or actions on the landing page directly.
App intent
App intent URLs are used to trigger an Intent in an app. When an app intent URL is received, the associated app responds to the parameters contained in the URL, provided that the corresponding app intent filter is present. If the app is not installed, the user is taken to the Play Store to install the app. After the app is installed they can then launch the app and continue to the feature specified by the developer. App intent URLs are formatted as follows:
intent://host/path#Intent;scheme=yourscheme;package=com.yourapp.ui;end;
For more details about formatting intent URLs, see Android Intents with Chrome. Note that intent extras are not passed.
You can also construct the URL correctly by creating an intent, and then using
intent.toUri(Intent.URI_INTENT_SCHEME),
as shown here:
Intent intent = new Intent()
.setData(new Uri.Builder()
.scheme("yourscheme")
.authority("host")
.appendPath("path")
.build())
.setPackage("com.yourapp.ui");
Log.i(TAG, "Use this intent url: " + intent.toUri(Intent.URI_INTENT_SCHEME));
Free-form app intent
This option should be used for app intents that cannot match the scheme, path, and package name format. Only use this option if you are sure your intent URL is properly formatted.
You may choose to send the user to a specified URL instead of the Play Store in the event that the app is not installed by adding a S.browser_fallback_url parameter to the intent:
intent://host/path#Intent;scheme=yourscheme;package=com.yourapp.ui; \
S.browser_fallback_url=http%3A%2F%2Fm.yoursite.com%2Fpath%2F%;end;
Context targeting
Rules
Nearby Notifications supports four targeting rules:
Date
dateStart and dateEnd are used to specify the date range within which
the attachment is visible, in ISO 8601 format.
The following example shows notification during January of 2017.:
{
"title": "January 2017",
"url": "https://www.example.com",
"targeting":[
{
"startDate": "2017-01-01",
"endDate": "2017-01-31"
}
]
}
Time of day
"timeOfDayStart" and "timeOfDayEnd" are used to specify the daily time range within which the attachment is visible, in ISO 8601 format. The following example shows notification from 9AM to 5PM daily:
{
"title": "Work time",
"url": "https://www.example.com",
"targeting":[
{
"startTimeOfDay": "9:00",
"endTimeOfDay": "17:00"
}
]
}
Day of week
"anyOfDaysOfWeek" is used to specify the days of week when the attachment is visible. The format is ISO 8601, from 1(Monday) to 7(Sunday). The following example shows notification on Saturday and Sunday:
{
"title": "Weekends",
"url": "https://www.example.com",
"targeting":[
{
"anyOfDaysOfWeek": [6, 7]
}
]
}
App install state
"anyOfAppInstallStates" is for setting attachment visibility based on app install states. It only works for App intent URL. The following example shows notification when the app is not installed.
{
"title": "App not installed",
"url": "intent://host/path#Intent;package=com.example",
"targeting":[
{
"anyOfAppInstallStates": ["NOT_INSTALLED"]
}
]
}
Combination of rules
For each attachment, there can be multiple targeting rules. Rules from the same targeting object are ANDed together. The following example shows a notification from 9AM to 5PM on Saturdays and Sundays.
{
"title": "Weekend and work time",
"url": "https://www.example.com",
"targeting":[
{
"startTimeOfDay": "9:00",
"endTimeOfDay": "17:00"
"anyOfDaysOfWeek": [6, 7]
}
]
}
Rules from the different targeting objects are ORed togeter. The following example shows a notification from 9AM to 5PM daily Monday through Friday, plus all day on Saturdays and Sundays.
{
"title": "Weekend or work time",
"url": "https://www.example.com",
"targeting":[
{
"anyOfDaysOfWeek": [6, 7]
},
{
"startTimeOfDay": "9:00",
"endTimeOfDay": "17:00"
}
]
}
Add an intent filter to your app
Apps must be configured to handle the scheme, host, and path for the given URL.
To do this, you must add an element in your AndroidManifest.xml to declare an
<intent-filter> that
matches the scheme, host, and path and mark it browsable with a category
filter, as shown here:
<intent-filter>
<action android:name="android.intent.action.VIEW"/>
<!-- both categories below are required -->
<category android:name="android.intent.category.BROWSABLE"/>
<category android:name="android.intent.category.DEFAULT"/>
<data android:host="host"
android:pathPrefix="/path"
android:scheme="yourscheme"/>
</intent-filter>
To learn more, see Handling App Links.