Frequently Asked Questions

How do I make a great attachment?

Nearby Notifications will display messages in the Nearby section of Google Settings, light up the Nearby Quick Settings tile on supported devices, and will promote the best performing attachments as notifications.

For maximum effectiveness, attachments should:

  • Point users to apps or websites that some users already visit in that location.
  • Be appealing to most users who will receive the notification.
  • Optimizing the beacon location may help target only interested users.
  • Have a direct call to action and avoid surprising the user.
  • Strive for messages that receive positive user engagement.
  • Adhere to the Nearby Notifications policies to maintain a positive experience for our users.

My attachment doesn't show in the Nearby section of Google Settings. Why?

  • There are a few constraints on messages we show, such as only allowing HTTPS URLs and disallowing content that violates our policies.
  • Links to play.google.com are not supported. Instead use App Intent attachments to enable an experience powered by an app.

My message is not being shown as a notification. Why?

There are several reasons a notification may not appear.

  1. A notification won't show if the attachment is not well received by users. Tips for creating a great attachment can be found above.
  2. Nearby Notifications typically scans for beacons for a few seconds after the screen is turned on. If the screen has not been turned on for a while, the device won't discover new beacons.
  3. An attachment in Debug mode will only show on debug mode devices. Also see Debug mode
  4. If the notification has been dismissed on a device recently, that device may not show another notification a period of time. The backoff policy is also reset if the user opens the Nearby section of Google Settings.
  5. A notification may not show if it violates the Nearby Notifications policies.

Which Android versions support Nearby Notifications?

Nearby Notifications is supported on Android 4.4 (KitKat) and newer.

How does Nearby Notifications relate to Eddystone-URL or Physical Web?

Nearby Notifications works in parallel with Eddystone-URL and Physical Web with the exact behavior depending on your use-cases and capabilities. For example, if you have one use-case that is available on your website, you might use an Eddystone-URL beacon. If the use-case is available in your app, you might use Nearby Notifications with an app intent.

What is the required format for Nearby Notifications attachments in the Proximity Beacon API?

See Attachment Data Format for details. In short, attachments should take the following form:

    {
      "title": "Example",
      "url": "https://www.example.com"
    }

In the Nearby Notifications attachments, how is title used?

The title will appear in the notifications and lists that are displayed by Nearby Notifications. For example, if your title is set to "Example action at place", the notification text will appear as "Example action at place" in addition to the app name or URL.

Does Nearby Notifications install the app in the background?

No. Nearby Notifications will redirect users to the Google Play Store to install from there.

How do I know if a user came to my app via Nearby Notifications?

Nearby Notifications links are standard Android deep links, but if you want to supply additional tags, for example, for metrics or analytics, you can add query string parameters into the path component of the intent URL.

Does Nearby Notifications support iBeacon?

Yes, as long as the beacon has a static iBeacon ID. These IDs can be registered in the Proximity Beacon API, and can have Nearby Notifications attachments.

Where and when does the scanning happen, if not in my app?

The scanning is performed by Google Play Services, and only at "screen-on" events.

Who is responsible for registering the beacons in the Proximity Beacon API?

Anyone can register the beacon, as long as the attachment has the right namespace and type. In most cases this will be the owner of the beacon, but may be the beacon OEM if you are under contract with them.

What is the format of the app intent URI?

First, with the Beacon Dashboard you can let the web frontend construct a valid URI for you provided you understand the scheme, host, and path parts of the URI. Here's an example:

If you want Nearby Notifications to launch the activity in your app that has the following intent filter:

    <data android:host="item"
          android:pathPrefix="/scanner"
          android:scheme="myapp" />

The corresponding intent:// URI would be:

    intent://item/scanner#Intent;scheme=myapp;package=com.myapp;end

That is, the URI can be broken up as such:

    intent://<host>/<path>#Intent;scheme=<scheme>;package=<package name>;end

If your activity requires intent extras, these should be added just before ;end:

    intent://item/scanner#Intent;scheme=myapp;package=com.myapp;S.string_extra=value%20one;B.bool_extra=true;end

The following types can be used in extras:

  • Boolean
  • Byte
  • Char
  • Double
  • Float
  • Int
  • Long
  • Short

Also see Intent.java#parseUri() and Intent.java#toUri(int) in the context of URI_INTENT_SCHEME for more details about this intent URL.

What about localization of the title Nearby Notifications uses?

Nearby Notifications attachments must include the language/locale as part of the namespace/type, and Nearby Notifications will only surface those attachments that match the user's locale settings.