> [!WARNING]
> **Warning:** Nearby Messages is deprecated and will stop working as of December 2023. Please navigate to [Nearby Connections](https://developers.google.com/nearby/connections/overview.md.txt) for further support or [Migration Guideline](https://developers.google.com/nearby/messages/android/migrate-to-nc.md.txt) on how to migrate existing Nearby Messages usages to Nearby Connections.

> [!WARNING]
> **Warning:** Nearby Messages on Android will cease supporting ultrasonic advertising and discovery beginning August 1, 2021. Advertising and discovery will still occur over Bluetooth.

This document explains how to start developing with the Nearby Messages API on
Android. The Nearby Messages API is part of
[Google Play services](https://developer.android.com/google/play-services/index.html).

## Step 1: Get Google Play services

The Nearby Messages API is available on Android devices with
[Google Play services](https://developer.android.com/google/play-services/index.html)
7.8.0 or higher. Devices running Android 2.3 or higher that have the Google
Play Store app automatically receive updates to Google Play services. To check
which version of Google Play services is installed on your device, go to
**Settings \> Apps \> Google Play services**.

Ensure that you have the latest client library for Google Play services on your
development host:

1. Open the [Android SDK Manager](https://developer.android.com/sdk/installing/adding-packages.html).
2. Under **Appearance \& Behavior \> System Settings \> Android SDK \> SDK Tools**,
   ensure that the following packages are installed:

   - Google Play services
   - Google Repository

## Step 2: Get a Google account

To use the Nearby Messages APIs, you need a [Google Account](https://www.google.com/accounts/NewAccount).
This is so that you, the developer, can enable the Nearby API in the next
step (your users will not need to have a Google account).
If you already have an account, then you're all set. You may also want a
separate Google Account for testing purposes.

## Step 3: Get an API key

Take these steps to enable the Google Nearby Messages API for Android and get
an API key:

1. Go to the [Google Developers Console](https://console.developers.google.com/flows/enableapi?apiid=copresence&keyType=CLIENT_SIDE_ANDROID&reusekey=true).
2. Create or select a project to register your application with.
3. Click **Continue** to Enable the API.
4. On the **Credentials** page, create a new **Android key** (and set the API Credentials).  
   Note: If you have an existing **Android key**, you may use that key.
5. In the resulting dialog, enter your app's [SHA-1 fingerprint](https://developers.google.com/nearby/messages/android/get-started.md.txt#obtain_the_sha1_fingerprint_of_your_certificate) and package name. For example:

   ```
   BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
   ```

   ```
   com.example.android.nearbyexample
   ```
6. Your new Android API key appears in the list of API keys for your project. An API key is a string of characters, something like this:

   ```
   AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
   ```

### Obtain the SHA1 fingerprint of your certificate

To create a new API key for your Android app, you need the SHA1 fingerprint
of the certificate you use to sign your APK. Messages can only be exchanged
between apps that are signed with API keys from the same project.

To obtain this fingerprint:

1. Find the location of your keystore.
2. In a terminal, run the `keytool` utility from the JDK. For example, if you are using the `` `debug` `` keystore:

```
$ keytool -alias \
androiddebugkey -keystore \
~/.android/debug.keystore -list -v
```
3. **Note:** For the debug keystore, the password is `android`. On Mac OS and Linux, the debug keystore is typically located at `~/.android/debug.keystore`. On Windows, it is typically located at `%USERPROFILE%\.android\debug.keystore`.
4. The output of the `keytool` command contains the SHA1 fingerprint for the certicate.

> [!NOTE]
> **Note:** If you are also developing an iOS app, or using the Proximity Beacon REST API, make sure you generate all respective API keys within the same Google Developers Console project. For more information, see the [Getting Started guide for iOS](https://developers.google.com/nearby/messages/ios/get-started.md.txt), and [Get Started with the REST API](https://developers.google.com/beacons/proximity/get-started).

## Step 4: Configure your project

[Android Studio](https://developer.android.com/sdk/installing/studio.html) makes it
easy to create a project for the Nearby Messages API. Follow the steps described
in [Creating a Project](https://developer.android.com/sdk/installing/create-project.html)
to create a new project. In Android Studio, open the `build.gradle` file for
your module and add the Google Play services client library as a dependency:

```
apply plugin: 'android'
...

dependencies {
    compile 'com.google.android.gms:play-services-nearby:19.5.1'
}
```

Then, configure your manifest with the API Key generated in the previous step:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.google.sample.app" >
        <application ...>
            <meta-data
                android:name="com.google.android.nearby.messages.API_KEY"
                android:value="API_KEY" />
            <activity>
            ...
            </activity>
        </application>
    </manifest>

## Step 5: Publish and subscribe

In your app, start using the Nearby Messages API.

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        mMessageListener = new MessageListener() {
            @Override
            public void onFound(Message message) {
                Log.d(TAG, "Found message: " + new String(message.getContent()));
            }

            @Override
            public void onLost(Message message) {
                Log.d(TAG, "Lost sight of message: " + new String(message.getContent()));
            }
        }

        mMessage = new Message("Hello World".getBytes());
    }

    @Override
    public void onStart() {
        super.onStart();
        ...
        Nearby.getMessagesClient(this).publish(mMessage);
        Nearby.getMessagesClient(this).subscribe(mMessageListener);
    }

    @Override
    public void onStop() {
        Nearby.getMessagesClient(this).unpublish(mMessage);
        Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
        ...
        super.onStop();
    }

The Nearby Messages API requires user consent. When either publish or subscribe
is first invoked, Nearby will show an opt in dialog.