{"id":13776995,"url":"https://github.com/Driversnote-Dev/react-native-kontaktio","last_synced_at":"2025-05-11T10:31:35.068Z","repository":{"id":39706853,"uuid":"63321496","full_name":"Driversnote-Dev/react-native-kontaktio","owner":"Driversnote-Dev","description":"React Native (iOS and Android) library for Kontakt.io beacons (and all other beacons)","archived":false,"fork":false,"pushed_at":"2024-09-16T22:22:22.000Z","size":23958,"stargazers_count":115,"open_issues_count":35,"forks_count":49,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-25T03:15:28.410Z","etag":null,"topics":["beacon","ibeacon","kontaktio"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Driversnote-Dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-14T09:18:03.000Z","updated_at":"2025-03-13T00:42:46.000Z","dependencies_parsed_at":"2023-02-08T05:31:14.791Z","dependency_job_id":"1dacba4b-586b-42c3-85d4-ac87f087db2d","html_url":"https://github.com/Driversnote-Dev/react-native-kontaktio","commit_stats":{"total_commits":308,"total_committers":17,"mean_commits":18.11764705882353,"dds":"0.25649350649350644","last_synced_commit":"ce932cb127f505a939dea59882269ef292abf842"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Driversnote-Dev%2Freact-native-kontaktio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Driversnote-Dev%2Freact-native-kontaktio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Driversnote-Dev%2Freact-native-kontaktio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Driversnote-Dev%2Freact-native-kontaktio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Driversnote-Dev","download_url":"https://codeload.github.com/Driversnote-Dev/react-native-kontaktio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252949272,"owners_count":21830151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beacon","ibeacon","kontaktio"],"created_at":"2024-08-03T18:00:36.131Z","updated_at":"2025-05-11T10:31:30.012Z","avatar_url":"https://github.com/Driversnote-Dev.png","language":"Objective-C","readme":"# react-native-kontaktio [![npm version](https://badge.fury.io/js/react-native-kontaktio.svg)](https://badge.fury.io/js/react-native-kontaktio)\n\nCross-platform React Native module for detecting beacons with **Android** and **iOS** devices.\n\nKontakt.io SDK Versions of newest release:\n\n| OS          | SDK Version                                                                                          |\n| :---------- | :--------------------------------------------------------------------------------------------------- |\n| **Android** | [7.0.6](https://kontakt-api-docs.stoplight.io/docs/dev-ctr-sdks/423dcaf4067cc-android-sdk-changelog) |\n| **iOS**     | [3.0.25](https://github.com/kontaktio/kontakt-ios-sdk/releases/tag/v3.0.25)                          |\n\n## Advantages\n\n- Works with any beacon (because the Kontakt.io SDK wraps the native beacon libraries (while adding more) - no Kontakt.io SDK API key is necessary.\n- Especially useful with [Kontakt.io](http://kontakt.io/) beacons because additional information like the **unique id** (on the back of each beacon), the **battery power level** and others are available and get synchronized with your Kontakt.io online panel.\n- Highly customizable configurations (e.g. for setting arbitrary monitoring intervals on Android)\n\n## Setup\n\n- [Android Setup](/docs/setup.android.md)\n- [iOS Setup](/docs/setup.ios.md)\n\n## API Documentation\n\n- [Android Documentation](/docs/api.android.md)\n- [iOS Documentation](/docs/api.ios.md)\n\n## Examples\n\n### Extensive Example\n\n- [Android extensive Example](/Example/src/Example.android.js)\n- [iOS extensive Example](/Example/src/Example.ios.js)\n\n### Minimal TypeScript Example\n\nA minimal example (created with [React Native v0.69.5](https://github.com/facebook/react-native/releases/tag/v0.69.5) and TypeScript) with the default configuration and no specifically set regions. Thus, the default region `everywhere` (i.e. all beacons) is automatically used.\n\n1. Follow the setup instructions carefully for `iOS` and `Android` to install `react-native-kontaktio` for both platforms.\n2. Start a new React Native TypeScript project (`npx react-native init BeaconTest --template react-native-template-typescript`) and replace `App.tsx` with the example code below.\n3. Run the app on a real device (`iOS` or `Android` - not a simulator)\n4. Check the React Native logs to see console statements containing incoming beacon signals.\n\n```ts\nimport React, { useEffect } from 'react';\nimport {\n  Alert,\n  DeviceEventEmitter,\n  NativeEventEmitter,\n  PermissionsAndroid,\n  Platform,\n  SafeAreaView,\n  StatusBar,\n  StyleSheet,\n  Text,\n  View,\n} from 'react-native';\n\nimport Kontakt, { KontaktModule } from 'react-native-kontaktio';\nconst {\n  connect,\n  init,\n  startDiscovery,\n  startRangingBeaconsInRegion,\n  startScanning,\n} = Kontakt;\n\nconst kontaktEmitter = new NativeEventEmitter(KontaktModule);\n\nconst isAndroid = Platform.OS === 'android';\n\n/**\n * Android Marshmallow (6.0) and above need to ask the user to grant certain permissions.\n * This function does just that.\n */\nconst requestLocationPermission = async () =\u003e {\n  try {\n    const granted = await PermissionsAndroid.request(\n      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,\n      {\n        title: 'Location Permission',\n        message:\n          'This example app needs to access your location in order to use bluetooth beacons.',\n        buttonNeutral: 'Ask Me Later',\n        buttonNegative: 'Cancel',\n        buttonPositive: 'OK',\n      }\n    );\n    if (granted === PermissionsAndroid.RESULTS.GRANTED) {\n      return true;\n    } else {\n      // permission denied\n      return false;\n    }\n  } catch (err) {\n    console.warn(err);\n    return false;\n  }\n};\n\nconst beaconSetup = async () =\u003e {\n  if (isAndroid) {\n    // Android\n    const granted = await requestLocationPermission();\n    if (granted) {\n      await connect();\n      await startScanning();\n    } else {\n      Alert.alert(\n        'Permission error',\n        'Location permission not granted. Cannot scan for beacons',\n        [{ text: 'OK', onPress: () =\u003e console.log('OK Pressed') }],\n        { cancelable: false }\n      );\n    }\n  } else {\n    // iOS\n    await init();\n\n    /**\n     * Will discover Kontakt.io beacons only\n     */\n    await startDiscovery();\n\n    /**\n     * Works with any beacon(also virtual beacon, e.g. https://github.com/timd/MactsAsBeacon)\n     * Requires user to allow GPS Location (at least while in use)\n     *\n     * change to match your beacon values\n     */\n    await startRangingBeaconsInRegion({\n      identifier: '',\n      uuid: 'A4826DE4-1EA9-4E47-8321-CB7A61E4667E',\n      major: 1,\n      minor: 34,\n    });\n  }\n\n  // Add beacon listener\n  if (isAndroid) {\n    /* works with any beacon */\n    DeviceEventEmitter.addListener(\n      'beaconsDidUpdate',\n      ({ beacons, region }) =\u003e {\n        console.log('beaconsDidUpdate', { beacons, region });\n      },\n    );\n  } else {\n    /* works with Kontakt.io beacons only */\n    kontaktEmitter.addListener('didDiscoverDevices', ({ beacons }) =\u003e {\n      console.log('didDiscoverDevices', { beacons });\n    });\n\n    /* works with any beacon */\n    kontaktEmitter.addListener('didRangeBeacons', ({ beacons, region }) =\u003e {\n      console.log('didRangeBeacons', { beacons, region });\n    });\n  }\n};\n\nconst App: React.FC = () =\u003e {\n  useEffect(() =\u003e {\n    Promise.resolve().then(beaconSetup);\n\n    return () =\u003e {\n      // remove event listeners\n      if (isAndroid) {\n        kontaktEmitter.removeAllListeners('beaconsDidUpdate');\n      } else {\n        kontaktEmitter.removeAllListeners('didDiscoverDevices');\n        kontaktEmitter.removeAllListeners('didRangeBeacons');\n      }\n    };\n  }, []);\n\n  return (\n    \u003cSafeAreaView\u003e\n      \u003cStatusBar barStyle=\"dark-content\" /\u003e\n      \u003cView style={styles.wrapper}\u003e\n        \u003cText style={styles.title}\u003ereact-native-kontaktio Example\u003c/Text\u003e\n        \u003cText\u003eCheck console.log statements\u003c/Text\u003e\n      \u003c/View\u003e\n    \u003c/SafeAreaView\u003e\n  );\n};\n\nconst styles = StyleSheet.create({\n  wrapper: {\n    height: '100%',\n    justifyContent: 'center',\n    alignItems: 'center',\n  },\n  title: {\n    paddingVertical: 10,\n    fontSize: 30,\n  },\n});\n\nexport default App;\n```\n\n---\n\n**Note (March 2020)**: The example in the `Example/` folder is a bit outdated. If you want to try to run the example app anyway, here are some instructions to do so:\n\n1.  Clone this repository, connect an Android and/or Apple device to your computer and have some (Kontakt.io) beacons nearby.\n\n2.  Open a terminal window, bash to the `Example/` folder, run `npm install` and start the react-native server\n\n    ```bash\n    $ cd react-native-kontaktio/Example\n    $ npm install\n    $ npm start\n    ```\n\n3.  Build the example and run it on your device. The app will appear under the name `KontaktIoSimpleTest`:\n\n    - Android:\n\n      ```bash\n      $ react-native run-android\n      ```\n\n    - iOS\n\n      ```bash\n      $ react-native run-ios\n      ```\n\n## Further notes\n\n- Beacons support is part of Android versions 4.3 and up. \\* So far the lowest Android version this library was tested on was a device with Android 4.4.2.\n- A physical device must be used for testing and some beacons (Kontakt.io beacons to be able to use all features).\n- If some BLE Beacons are filtered out by the scan on Android 12+, therefore not returned in the list of beacons, try this:\n  ```xml\n  \u003cuses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" tools:remove=\"android:usesPermissionFlags\" /\u003e\n  ```\n  With the **neverForLocation** android:usesPermissionFlags, some BLE beacons are filtered from the scan results. |More information about this on [issue #121](https://github.com/Driversnote-Dev/react-native-kontaktio/issues/121#issuecomment-2098884380).\n\n\n\n## ToDo:\n\n- Update Android Eddystone feature:\n\n  - Add _multiple_ Eddystone namespaces, i.e. add function `setEddystoneNamespaces`\n  - Add Eddystone Frames Selection configuration option\n\n## Contribute\n\n### Test library changes locally\n\n1. Fork and clone this repository\n2. Run `yarn` to install the dependencies\n3. Make code changes\n4. Delete `lib` folder if it exists and run `yarn tsc` to compile the TypeScript files in the the `lib` folder.\n5. In the `package.json` file of an example app point to the this directory, e.g.\n\n    ```json\n    \"dependencies\": {\n      ...\n      \"react-native-kontaktio\": \"../react-native-kontaktio\"\n    },\n    ```\n6. Build and run on a real device\n\n### Upgrade to a new version of the Kontakt.io SDK\n\n#### Android\n\nIn `build.gradle` file change the version in the following line\n\n```\nimplementation \"io.kontakt.mvn:sdk:7.0.6\"\n```\n\n#### iOS\n\n1. Go to the [Kontakt.io SDK releases page](https://github.com/kontaktio/kontakt-ios-sdk/releases) and download the newest version of  **KontaktSDK.framework.zip**.\n2. Replace the `ios/KontaktSDK.framework` folder of this library with the `Cocoapods/KontaktSDK/iOS/KontaktSDK.xcframework/ios-arm64_armv7/KontaktSDK.framework` folder which you find in the unzipped folder structure.\n","funding_links":[],"categories":["\u003ca name=\"Network:-Native-Modules\"\u003eNetwork: Native Modules\u003c/a\u003e"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDriversnote-Dev%2Freact-native-kontaktio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDriversnote-Dev%2Freact-native-kontaktio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDriversnote-Dev%2Freact-native-kontaktio/lists"}