# Attachment Data Format

The easiest way to add Nearby Notifications attachments is though the
[Google Beacon Dashboard](https://developers.google.com/beacons/dashboard).
Alternatively, you may use the
[Proximity Beacon API](https://developers.google.com/beacons/proximity/guides) and the attachment data format described below.

> [!NOTE]
> **Note:** Adhere to the [Nearby Notifications
> policies](https://developers.google.com/nearby/notifications/policies) to maintain a positive experience for our users.

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 `title` should 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`, or `Learn 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](https://developers.google.com/nearby/notifications/attachment_data_format#web_url)
- [App Intent](https://developers.google.com/nearby/notifications/attachment_data_format#app_intent)
- [Free-form App Intent](https://developers.google.com/nearby/notifications/attachment_data_format#free-form_app_intent)

### 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](https://developer.chrome.com/multidevice/android/intents).
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)`](https://developer.android.com/reference/android/content/Intent.html#toUri(int)),
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](https://developers.google.com/nearby/notifications/attachment_data_format#date)
- [Time of day](https://developers.google.com/nearby/notifications/attachment_data_format#time_of_day)
- [Day of week](https://developers.google.com/nearby/notifications/attachment_data_format#day_of_week)
- [App install state](https://developers.google.com/nearby/notifications/attachment_data_format#app_install_state)

#### 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](https://developers.google.com/nearby/notifications/attachment_data_format#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](http://developer.android.com/training/app-links/index.html).