# react-native-estimote-proximity

React Native wrapper for Estimote Proximity SDK.

You can read more about Estimote Proximity on [developer.estimote.com](https://developer.estimote.com).

- [Installation](#installation)
- [Location permission](#location-permission)
- [Background support](#background-support)
- [Usage & examples](#usage--examples)
- [Contact & feedback](#contact--feedback)

## Installation

```
$ npm install react-native-estimote-proximity --save
$ react-native link react-native-estimote-proximity
```

On **iOS**, you also need to add Estimote Proximity SDK and its dependencies to your app's Xcode project. The easiest way to do that is via CocoaPods:

1. Install CocoaPods: https://cocoapods.org

2. In the `ios` directory of your app, add a `Podfile` with this content:

   ```ruby
   platform :ios, '10.0'

   target 'NAME_OF_YOUR_APP' do
     pod 'EstimoteProximitySDK'
   end
   ```

   The `NAME_OF_YOUR_APP` is usually the same thing you used with `react-native init`.

3. Inside the `ios` directory, run:

   ```
   $ pod --repo-update install
   ```

On **Android**, you need to bump the `minSdkVersion` of your app to 18, since that's the lowest Estimote Proximity SDK supports. In the `android/app/build.gradle` file: find `minSdkVersion 16` and change it to `18`.

## Location permission

Since detecting proximity to Bluetooth beacons gives you some idea of the user's location, both iOS and Android require that the user agrees to that, even though we're not actually using GPS or the likes. Location services must also be globally enabled in the system.

```javascript
import * as RNEP from 'react-native-estimote-proximity'

// this will trigger a popup with "allow this app to access your location?"
RNEP.locationPermission.request()
  .then(permission => { // this is the user's decision
    // permission can be equal to:
    // * RNEP.locationPermission.DENIED - proximity detection won't work
    // * RNEP.locationPermission.WHEN_IN_USE - only when the app is active
    // * RNEP.locationPermission.ALWAYS - even when the app is not active
  })
```

On **iOS**, you also need to make sure you have the following entries in your app's Info.plist file: (you'll usually find it at `ios/APP_NAME/Info.plist`)

  ```xml
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We'll show you things near you in the app.</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We'll show you things near you in the app. With "always" access, we'll
          also send you notifications when you're near something interesting.</string>
  ```

These are the messages that iOS will show as part of the location permission popup.

On **Android**, you need to bump the `targetSdkVersion` of your app to 23, since that's when the new permissions system was introduced. In the `android/app/build.gradle` file: find `targetSdkVersion 22` and change it to `23`.

## Background support

Other than obtaining the `ALWAYS` location permission, there's just a little bit more to do if you want your app to keep getting the enter/exit/change callbacks in the background.

On **iOS**, you need to:

1. Open the Xcode project.
2. Click on the top-level item in the project navigator to access the project settings.
3. Make sure your app is selected in the "TARGETS" section.
4. Go to the "Capabilities" tab.
5. Enable "Background Modes" and check "Uses Bluetooth LE accessories".

On **Android**, you need to:

1. Make sure your target API level is at least 23.
   - In the `android/app/build.gradle` file: find `targetSdkVersion 22` and change it to `23`.
2. [TBD]

## Usage & examples

Check `example/index.js` for a quick run-down of how to use this library.

You can run the example app with the usual `react-native run-android` and `run-ios`. Note that iOS and Android simulators don't support Bluetooth, so **you need to run it on a physical device**.

To run the example on iOS, you also need to install pods (dependencies) first:

1. Install CocoaPods: https://cocoapods.org
2. Inside the `example/ios` directory, run:

   ```
   $ pod --repo-update install
   ```

## Contact & feedback

Let us know your thoughts, feedback, and questions on [forums.estimote.com][forums].

[forums]: https://forums.estimote.com