Installation

Installation

Adding Nearby Settings to your app is easy. Just follow these steps to get started.

Before you get started

Nearby Settings is still being developed, some things might not work yet.

  • SettingSchema#constraints is not yet implemented for SettingType.MULTI_SELECT and SettingType.NUMBER contrary to the documentation.

Add required permissions for Nearby Connections

These settings are required to use Nearby Settings in your app. Add the following permissions to your AndroidManifest.xml file:

<!-- Required for Nearby Connections -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:minSdkVersion="29"
    android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:minSdkVersion="31"
    android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:minSdkVersion="31"
    android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:minSdkVersion="31"
    android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:minSdkVersion="32"
    android:name="android.permission.NEARBY_WIFI_DEVICES" />

Add Nearby Settings to your app

Add the following dependency to your build.gradle file:

Add the JitPack repository to your build file (if you haven’t already)
  dependencyResolutionManagement {
  	repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  	repositories {
  		mavenCentral()
          maven { url = java.net.URI("https://jitpack.io") }
  	}
  }
	dependencies {
	        implementation("com.github.Turtlepaw:nearby_settings:1.0.1")
	}

Create a NearbySettingsHost

Create a NearbySettingsHost in your app to handle the connection between your app and the mobile device. You can use the following code as a starting point:

Define a schema
val defaultSchema = SettingsSchema(
    schemaItems = listOf(
        SettingSchema(
            key = "text_input",
            label = "Text Input",
            type = SettingType.TEXT,
        ),
        SettingSchema(
            key = "number_input",
            label = "Number Input",
            type = SettingType.NUMBER,
        ),
        SettingSchema(
            key = "toggle_input",
            label = "Toggle Input",
            type = SettingType.TOGGLE,
        ),
        SettingSchema(
            key = "select_input",
            label = "Select Input",
            type = SettingType.SELECT,
            constraints = SettingConstraints(
                options = listOf("option1", "option2", "option3")
            )
        ),
        SettingSchema(
            key = "multiselect_input",
            label = "Multiselect Input",
            type = SettingType.MULTI_SELECT,
            constraints = SettingConstraints(
                options = listOf("option1", "option2", "option3")
            )
        )
    )
);
Create a NearbySettingsHost
// Create a mutable state for the schema
// so when the settings change it will reflect on the UI
var schema by remember { mutableStateOf(defaultSchema) }
 
val settingsHost = NearbySettingsHost(
    settingsSchema = defaultSchema,
    onSettingsChanged = { newSettings ->
        schema = newSettings
    },
    context = this,
    // If you want data to be stored persistently
    // `NearbySettings` will store and retrieve it
    enablePersistence = true,
    // If you want to start advertising on start
    automaticallyStart = true,
    appDetails = AppDetails(
        // These are required and shown to the user
        label = "My Nearby Settings App",
        developer = "Your Developer Name",
        // Provide a way for users to contact you
        // This is currently optional but may be enforced in the future
        contact = "dev@example.com",
        // Provide a website for users to visit (optional)
        website = "https://nearbysettings.pages.dev/"
    )
)

If you’re using Jetpack Compose, remember to add a remember block to the NearbySettingsHost:

val settingsHost = remember {
    NearbySettingsHost(
        // ...
    )
}
Show the auth dialog

This is required to show the authentication dialog to the user, verifying that the is connecting to the correct device. Add this Jetpack Compose code to show the dialog:

setContent {
    settingsHost.AuthScreen()
    //...
}

Defining app details

Starting in 1.0.1, you can define app details to show to the user.

val settingsHost = NearbySettingsHost(
    // ...
    // Define app details shown to the user
    appDetails = AppDetails(
        label = "My Nearby Settings App",
        developer = "Your Developer Name",
        // Provide a way for users to contact you, this is currently optional but may be enforced in the future.
        contact = "youremail@example.com",
        // Provide a website for users to visit (optional).
        website = "https://nearbysettings.pages.dev/"
    )
)

It will be rendered in a dialog containing the app details provided.

App Details
IntroductionDiscovery