Skip to content

R
react-native-device-info
Commit 8bdbca5e authored by Mehdi Achour's avatar Mehdi Achour
Browse files
Options

docs: rewrite the README file

parent a9f34bca
Show whitespace changes
Inline Side-by-side
Showing with 503 additions and 63 deletions
README.md
View file @ 8bdbca5e
......@@ -2,42 +2,59 @@
[![npm version](https://badge.fury.io/js/react-native-device-info.svg)](http://badge.fury.io/js/react-native-device-info)
Device Information for [React Native](https://github.com/facebook/react-native)
Device Information for [React Native](https://github.com/facebook/react-native).
## Install
## TOC
* [Installation](#installation)
* [Linking](#linking)
* [Usage](#usage)
* [API](#api)
* [Release Notes](#release-notes)
## Installation
Using npm:
```shell
npm install --save react-native-device-info
```
#### RN > 0.47 use 0.11 or higher
or using yarn:
## Automatically link
```shell
yarn addreact-native-device-info
```
#### With React Native 0.27+
> ⚠️ If you are on React Native > 0.47, you must use version 0.11.0 of this library or higher
## Linking
### Automatic
```shell
react-native link react-native-device-info
```
#### With older versions of React Native
You need [`rnpm`](https://github.com/rnpm/rnpm) (`npm install -g rnpm`)
(or using [`rnpm`](https://github.com/rnpm/rnpm) for versions of React Native < 0.27)
```shell
rnpm link react-native-device-info
```
## Manually link
### Manual
<details>
<summary>iOS (via Cocoa Pods)</summary>
### iOS (via Cocoa Pods)
Add the following line to your build targets in your `Podfile`
`pod 'RNDeviceInfo', :path => '../node_modules/react-native-device-info'`
Then run `pod install`
</details>
### iOS (without Cocoa Pods)
<details>
<summary>iOS (without Cocoa Pods)</summary>
In XCode, in the project navigator:
- Right click _Libraries_
......@@ -54,8 +71,10 @@ In XCode, in the project navigator, select your project.
Run your project (Cmd+R)
(Thanks to @brysgo for writing the instructions)
</details>
### Android
<details>
<summary>Android</summary>
- in `android/app/build.gradle`:
......@@ -119,8 +138,11 @@ include ':app'
```
(Thanks to @chirag04 for writing the instructions)
</details>
<details>
<summary>Windows</summary>
### Windows
- Open the solution in Visual Studio for your Windows apps
- right click your in the Explorer and click Add > Existing Project...
- Navigate to `./<app-name>/node_modules/react-native-device-info/windows/RNDeviceInfo` and add `RNDeviceInfo.csproj`
......@@ -142,68 +164,485 @@ include ':app'
```
(Thanks to @josephan for writing the instructions)
</details>
## Permissions
Add the appropriate, optional permissions to your `AndroidManifest.xml`:
## Usage
```xml
...
<uses-permission android:name="android.permission.BLUETOOTH"/> <!-- for Device Name -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> <!-- for Phone Number -->
```js
var DeviceInfo = require('react-native-device-info');
// or import DeviceInfo from 'react-native-device-info';
```
## Release Notes
## API
| Method | Return Type | iOS | Android | Windows | Since |
| ------------------------------------------------- | ------------------- | :---------: | :-----: | :-----: | ------ |
| [getAPILevel()](#getapilevel) | `number` | ❌ | ✅ | ❌ | 0.12.0 |
| [getApplicationName()](#getapplicationname) | `string` | ✅ | ✅ | ✅ | 0.14.0 |
| [getBrand()](#getbrand) | `string` | ✅ | ✅ | ✅ | 0.9.3 |
| [getBuildNumber()](#getbuildnumber) | `string` | ✅ | ✅ | ✅ | ? |
| [getBundleId()](#getbundleid) | `string` | ✅ | ✅ | ✅ | ? |
| [getCarrier()](#getcarrier) | `string` | ✅ | ✅ | ❌ | 0.13.0 |
| [getDeviceCountry()](#getdevicecountry) | `string` | ✅ | ✅ | ✅ | 0.9.0 |
| [getDeviceId()](#getdeviceid) | `string` | ✅ | ✅ | ✅ | 0.5.0 |
| [getDeviceLocale()](#getdevicelocale) | `string` | ✅ | ✅ | ✅ | 0.7.0 |
| [getDeviceName()](#getdevicename) | `string` | ✅ | ✅ | ✅ | ? |
| [getFirstInstallTime()](#getfirstinstalltime) | `number` | ❌ | ✅ | ❌ | 0.12.0 |
| [getIPAddress()](#getipaddress) | `Promise<string>` | ❌ | ✅ | ❌ | 0.12.0 |
| [getInstanceID()](#getinstanceid) | `string` | ❌ | ✅ | ❌ | ? |
| [getLastUpdateTime()](#getlastupdatetime) | `number` | ❌ | ✅ | ❌ | 0.12.0 |
| [getMACAddress()](#getmacaddress) | `Promise<string>` | ❌ | ✅ | ❌ | 0.12.0 |
| [getManufacturer()](#getmanufacturer) | `string` | ✅ | ✅ | ✅ | ? |
| [getMaxMemory()](#getmaxmemory) | `number` | ❌ | ✅ | ❌ | 0.14.0 |
| [getModel()](#getmodel) | `string` | ✅ | ✅ | ✅ | ? |
| [getPhoneNumber()](#getphonenumber) | `string` | ❌ | ✅ | ❌ | 0.12.0 |
| [getReadableVersion()](#getreadableversion) | `string` | ✅ | ✅ | ✅ | ? |
| [getSerialNumber()](#getserialnumber) | `string` | ❌ | ✅ | ❌ | 0.12.0 |
| [getSystemName()](#getsystemname) | `string` | ✅ | ✅ | ✅ | ? |
| [getSystemVersion()](#getsystemversion) | `string` | ✅ | ✅ | ✅ | ? |
| [getTimezone()](#gettimezone) | `string` | ✅ | ✅ | ✅ | ? |
| [getTotalMemory()](#gettotalmemory) | `number` | ✅ | ✅ | ❌ | 0.14.0 |
| [getUniqueID()](#getuniqueid) | `string` | ✅ | ✅ | ✅ | ? |
| [getUserAgent()](#getuseragent) | `string` | ✅ | ✅ | ❌ | 0.7.0 |
| [getVersion()](#getversion) | `string` | ✅ | ✅ | ✅ | ? |
| [is24Hour()](#is24hour) | `boolean` | ✅ | ✅ | ✅ | 0.13.0 |
| [isEmulator()](#isemulator) | `boolean` | ✅ | ✅ | ✅ | ? |
| [isPinOrFingerprintSet()](#ispinorfingerprintset) | (callback)`boolean` | ✅(iOS 9+) | ✅ | ❌ | 0.10.1 |
| [isTablet()](#istablet) | `boolean` | ✅ | ✅ | ✅ | ? |
---
### getAPILevel()
Gets the API level.
**Examples**
```js
const apiLevel = DeviceInfo.getAPILevel();
// iOS: ?
// Android: 25
// Windows: ?
```
See [CHANGELOG.md](https://github.com/rebeccahughes/react-native-device-info/blob/master/CHANGELOG.md)
**Notes**
> See [API Levels](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)
## Example
---
### getApplicationName()
Gets the application name.
**Examples**
```js
var DeviceInfo = require('react-native-device-info');
// or import DeviceInfo from 'react-native-device-info';
const appName = DeviceInfo.getApplicationName(); // "Learnium Mobile"
```
---
### getBrand()
Gets the device brand.
**Examples**
```js
const brand = DeviceInfo.getBrand();
// iOS: "Apple"
// Android: "Xiaomi"
// Windows: ?
```
| Name | Method | Return | Notes |
| :------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| Device Unique ID | `getUniqueID()` | `string` e.g. "FCDBD8EF-62FC-4ECB-B2F5-92C9E79AC7F9" | This is IDFV on iOS so it will change if all apps from the current apps vendor have been previously uninstalled. |
| Device Manufacturer | `getManufacturer()` | `string` e.g. "Apple" | |
| Device Brand | `getBrand()` | `string` e.g. "Apple / htc / Xiaomi" | |
| Device Model | `getModel()` | `string` e.g. "iPhone 6" | |
| Device ID | `getDeviceId()` | `string` e.g. "iPhone7,2" | Or the board on Android e.g. goldfish |
| Device is set to 24 hour time format | `is24Hour()` | `boolean` e.g. true | |
| System Name | `getSystemName()` | `string` e.g. "iPhone OS" | |
| System Version | `getSystemVersion()` | `string` e.g. "9.0" | |
| Bundle ID | `getBundleId()` | `string` e.g. "com.learnium.mobile" | |
| Build Number | `getBuildNumber()` | `string` e.g. "89" | |
| App Version | `getVersion()` | `string` e.g. "1.1.0" | |
| App Version (Readable) | `getReadableVersion()` | `string` e.g. "1.1.0.89" | |
| Device Name | `getDeviceName()` | `string` e.g. "Becca's iPhone 6" | |
| User Agent | `getUserAgent()` | `string` e.g. "Mozilla/5.0 (Linux; Android 8.0.0; Nexus 5X Build/OPR4.170623.009; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/61.0.3163.98 Mobile Safari/537.36" | |
| Device Locale | `getDeviceLocale()` | `string` e.g. "en-US" | |
| Device Country | `getDeviceCountry()` | `string` e.g. "US" | |
| Timezone | `getTimezone()` | `string` e.g. "America/Mexico_City" | |
| App is running in emulator | `isEmulator()` | `boolean` e.g. true | if app is running in emulator return true |
| App is running on a tablet | `isTablet()` | `boolean` e.g. true | if app is running on a tablet return true |
| PIN or fingerprint set | `isPinOrFingerprintSet()` | `(callback: (isPinOrFingerprintSet: boolean) => void) => void` | Only supported in Android and iOS 9.0 and above |
| API Level | `getAPILevel()` | `number` e.g. 25 | ANDROID ONLY - see [API Levels](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)|
| App Instance ID | `getInstanceID()` | `string` | ANDROID ONLY - see https://developers.google.com/instance-id/ |
| Phone Number | `getPhoneNumber()` | `?string` e.g. "2348675309" or "" | Only supported in Android |
| First Install Time | `getFirstInstallTime()` | `number` e.g. 1505607068808 | Only supported in Android |
| Last Install Time | `getLastUpdateTime()` | `number` e.g. 1505607068808 | Only supported in Android |
| Serial Number | `getSerialNumber()` | `string` | Only supported in Android |
| IP Address | `getIPAddress()` | `Promise<string>` | Only supported in Android |
| MAC Address | `getMACAddress()` | `Promise<string>` | Only supported in Android |
| Carrier | `getCarrier()` | `string` e.g. "SOFTBANK" | |
| Total Memory | `getTotalMemory()` | `number` e.g. 1995018240 | Total amount of memory on the device |
| Max Memory | `getMaxMemory()` | `number` e.g. 268435456 | ANDROID ONLY - see https://developer.android.com/reference/java/lang/Runtime.html#maxMemory() |
| App Name | `getApplicationName()` | `string` e.g.Learnium Mobile | |
Since the device setting for PIN/Fingerprint can be modified while the app is still open, this is available via callback instead of as a constant. To use, pass a callback function to the returned bridge function in your javascript:
```js
RNDeviceInfo.isPinOrFingerprintSet()(isPinOrFingerprintSet => {
---
### getBuildNumber()
Gets the application build number.
**Examples**
```js
const buildNumber = DeviceInfo.getBuildNumber();
// iOS: "89"
// Android: 4
// Windows: ?
```
**Notes**
> There is a type inconsistency: Android return an integer instead of the documented string.
---
### getBundleId()
Gets the application bundle identifier.
**Examples**
```js
const bundleId = DeviceInfo.getBundleId(); // "com.learnium.mobile"
```
---
### getCarrier()
Gets the carrier name (network operator).
**Examples**
```js
const carrier = DeviceInfo.getCarrier(); // "SOFTBANK"
```
---
### getDeviceCountry()
Gets the device country based on the locale information.
**Examples**
```js
const deviceCountry = DeviceInfo.getDeviceCountry(); // "US"
```
---
### getDeviceId()
Gets the device ID.
**Examples**
```js
const deviceId = DeviceInfo.getDeviceId();
// iOS: "iPhone7,2"
// Android: "goldfish"
// Windows: ?
```
---
### getDeviceLocale()
Gets the device locale.
**Examples**
```js
const deviceLocale = DeviceInfo.getDeviceLocale();
// iOS: "en"
// Android: "en-US"
// Windows: ?
```
---
### getDeviceName()
Gets the device name.
**Examples**
```js
const deviceName = DeviceInfo.getDeviceName();
// iOS: "Becca's iPhone 6"
// Android: ?
// Windows: ?
```
**Android Permissions**
* [android.permission.BLUETOOTH](https://developer.android.com/reference/android/Manifest.permission.html#BLUETOOTH)
---
### getFirstInstallTime()
Gets the time at which the app was first installed, in milliseconds.
**Examples**
```js
const firstInstallTime = DeviceInfo.getFirstInstallTime();
// Android: 1517681764528
```
---
### getIPAddress()
Gets the device current IP address.
**Examples**
```js
DeviceInfo.getIPAddress().then(ip => {
// "92.168.32.44"
})
```
**Android Permissions**
* [android.permission.ACCESS_WIFI_STATE](https://developer.android.com/reference/android/Manifest.permission.html#ACCESS_WIFI_STATE)
---
### getInstanceID()
Gets the application instance ID.
**Examples**
```js
const instanceId = DeviceInfo.getInstanceID();
// Android: ?
```
**Notes**
> See https://developers.google.com/instance-id/
---
### getLastUpdateTime()
Gets the time at which the app was last updated, in milliseconds.
**Examples**
```js
const lastUpdateTime = DeviceInfo.getLastUpdateTime();
// Android: 1517681764992
```
---
### getMACAddress()
Gets the network adapter MAC address.
**Examples**
```js
DeviceInfo.getMACAddress().then(mac => {
// "E5:12:D8:E5:69:97"
})
```
**Android Permissions**
* [android.permission.ACCESS_WIFI_STATE](https://developer.android.com/reference/android/Manifest.permission.html#ACCESS_WIFI_STATE)
---
### getManufacturer()
Gets the device manufacturer.
**Examples**
```js
const manufacturer = DeviceInfo.getManufacturer();
// iOS: "Apple"
// Android: "Google"
// Windows: ?
```
---
### getMaxMemory()
Returns the maximum amount of memory that the JVM will attempt to use, in bytes.
**Examples**
```js
const maxMemory = DeviceInfo.getMaxMemory();
// iOS: undefined
// Android: 402653184
// Windows: ?
```
---
### getModel()
Gets the device model.
**Examples**
```js
const model = DeviceInfo.getModel();
// iOS: ?
// Android: ?
// Windows: ?
```
---
### getPhoneNumber()
Gets the device phone number.
**Examples**
```js
const phoneNumber = DeviceInfo.getPhoneNumber();
// Android: ?
```
**Android Permissions**
* [android.permission.READ_PHONE_STATE](https://developer.android.com/reference/android/Manifest.permission.html#READ_PHONE_STATE)
---
### getReadableVersion()
Gets the application human readable version.
**Examples**
```js
const readableVersion = DeviceInfo.getReadableVersion();
// iOS: 1.0.1
// Android: 1.0.1
// Windows: ?
```
---
### getSerialNumber()
Gets the device serial number.
**Examples**
```js
const serialNumber = DeviceInfo.getSerialNumber();
// iOS: undefined
// Android: ?
// Windows: ?
```
---
### getSystemName()
Gets the device OS name.
**Examples**
```js
const systemName = DeviceInfo.getSystemName();
// iOS: "iOS"
// Android: "Android"
// Windows: ?
```
---
### getSystemVersion()
Gets the device OS version.
**Examples**
```js
const systemVersion = DeviceInfo.getSystemVersion();
// iOS: "11.0"
// Android: "7.1.1"
// Windows: ?
```
---
### getTimezone()
Gets the device default timezone.
**Examples**
```js
const timezone = DeviceInfo.getTimezone(); // "Africa/Tunis"
```
---
### getTotalMemory()
Gets the device total memory, in bytes.
**Examples**
```js
const totalMemory = DeviceInfo.getTotalMemory();
// iOS: ?
// Android: 1995018240
// Windows: ?
```
---
### getUniqueID()
Gets the device unique ID.
**Examples**
```js
const uniqueId = DeviceInfo.getUniqueId();
// iOS: "FCDBD8EF-62FC-4ECB-B2F5-92C9E79AC7F9"
// Android: "dd96dec43fb81c97"
// Windows: ?
```
**Notes**
> This is IDFV on iOS so it will change if all apps from the current apps vendor have been previously uninstalled.
---
### getUserAgent()
Gets the device User Agent.
**Examples**
```js
const userAgent = DeviceInfo.getUserAgent();
// iOS: "Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143"
// Android: ?
// Windows: ?
```
---
### getVersion()
Gets the application version.
**Examples**
```js
const version = DeviceInfo.getVersion();
// iOS: "1.0"
// Android: "1.0
// Windows: ?
```
---
### is24Hour()
Tells if the user preference is set to 24-hour format.
**Examples**
```js
const is24Hour = DeviceInfo.is24Hour(); // true
```
---
### isEmulator()
Tells if the application is running in an emulator.
**Examples**
```js
const isEmulator = DeviceInfo.isEmulator(); // false
```
---
### isPinOrFingerprintSet()
Tells if a PIN number or a fingerprint was set for the device.
**Examples**
```js
DeviceInfo.isPinOrFingerprintSet()(isPinOrFingerprintSet => {
if (!isPinOrFingerprintSet) {
...
}
}
```
**Notes**
> Since the device setting for PIN/Fingerprint can be modified while the app is still open, this is available via callback instead of as a constant.
---
### isTablet()
Tells if the device is a tablet.
**Examples**
```js
const isTablet = DeviceInfo.isTablet(); // true
```
## Release Notes
See the [CHANGELOG.md](https://github.com/rebeccahughes/react-native-device-info/blob/master/CHANGELOG.md).
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment