@yeomessagingcom/react-native-yeofr
v0.5.2
Published
React Native iOS and Android integration for YEO Face Recognition (device-only).
Readme
@yeomessagingcom/react-native-yeofr
iOS and Android face recognition bridge for React Native.
Recognition needs a real device. The package builds and runs in the
simulator — so an app that depends on it still compiles and its tests still
run — but activate there rejects with code E_UNAVAILABLE_SIMULATOR
(exported as UNAVAILABLE_ON_SIMULATOR), the same way the camera is
unavailable.
Versions
This README describes the newest release. For an older release, read the README at that version's tag — the engines and, since 0.5.0, the Android repository differ between versions.
| Bridge | iOS engine | Android engine | Android engine source |
|---|---|---|---|
| 0.5.2 | YEOFR 0.11.0 — Swift Package YEOFR-SPM at exact version, added to your app target | com.yeomessaging:yeofr-android:0.2.29 (16 KB page aligned native libraries) | YEO's private Maven repository, as for 0.5.0 — build settings yeoRepositoryUrl / yeoUser / yeoPassword (or the YEO_* environment variables); access from YEO support |
| 0.5.1, 0.5.0 | YEOFR 0.11.0, as above | com.yeomessaging:yeofr-android:0.2.28 | YEO's new private Maven repository — build settings yeoRepositoryUrl / yeoUser / yeoPassword (or the YEO_* environment variables); access from YEO support |
| 0.4.x | the previous iOS engine | the previous Android engine (0.1.x line) | the previous YEO repository — see the README at that version's tag |
The Android repository changed in 0.5.0. A repository block from a 0.4.x integration does not resolve the 0.2.x engine: set the new build settings described under Android and remove the old block.
Minimum deployment target is iOS 17.0. Apple-silicon Macs only for simulator builds — the xcframework has no Intel slice.
What changed in 0.5.2
- Android engine 0.2.29, 16 KB page aligned. 0.2.29 is 0.2.28 with its TensorFlow Lite runtime on 16 KB page aligned native libraries, which Google Play requires for apps targeting Android 15 and later (see 16 KB page size). No API or behaviour change, and galleries saved by 0.2.28 load unchanged. The iOS engine stays at 0.11.0.
- Android camera events no longer go through the interop event emitter. The
camera view dispatches
onEventthrough the UIManager event dispatcher, so React Native 0.87+ with the New Architecture no longer logs agetJSModule(RCTEventEmitter)warning on every analysed frame, and the view keeps working once React Native removes that interop path. SameonEventprop, same payloads.
From 0.5.0 or 0.5.1 there is nothing to change in JavaScript: update the
package and rebuild. If your app declares com.yeomessaging:yeofr-android
itself, move it to 0.2.29, and do not add org.tensorflow:tensorflow-lite
2.14 to your app. On Android Gradle Plugin 9, android.uniquePackageNames=false
is no longer needed for this engine; remove it if you set it only for YEOFR.
From 0.4.x, follow Upgrading to 0.5.0; you land on 0.2.29.
What changed from 0.4.5
The Android engine moves from the 0.1.x line to yeofr-android 0.2.28 (0.2.29
since 0.5.2), the
iOS engine moves to YEOFR 0.11.0 (both published), and both platforms gain
one liveness rule. Existing JavaScript keeps working.
- The client rule is
face.isLive. EveryFaceResult(camera events anddetectFaces) now carriesisLive: boolean, decided natively on both platforms asfaceState == Detected && isConfident()— the engine's own verdict at the engine's own bar.livenessGenuineis a deprecated alias ofisLiveand is nevernullany more. confidenceis display-only. It arrives as the engine's number for the frame, for display and debugging. Never thresholdconfidence; its scale and bar belong to the engine and move with it.- A framing hint on every result.
framingis'valid','noFace','multipleFaces','tooFar'or'tooClose', from the engine: a hint for the user (move closer / move back / one face at a time).tooFarandtooCloseare also what makestatusreadbadFraming, the same on both platforms. The hint is never part of the liveness decision. - Live only while one face is in view. With a second face present the
engine keeps its last verdict for up to 1.5 s;
isLiveisfalseandstatusisnotTrustedfor those frames. Expect a short run ofisLive: falsewhen a face first appears, while the engine gathers evidence. - Galleries saved by earlier engine versions are refused. Galleries
written by the 0.1.x Android and 0.9.x iOS engines do not load — on Android
loadTrackerFromDiskresolvesfalse(andloadTrackererror(-1)) and the engine stays unenrolled — so every user re-enrols once after upgrading. - iOS camera enrolment is a single front capture. The 0.11.0 session no
longer runs a guided pose walk:
enrolPosesis accepted for the shared prop contract but the capture reports onefrontpose, andisTargetMatchedsays whether the session is banking the frame. Android's paced walk is unchanged and now takes at least five seconds. - The Android engine comes from a new private YEO repository, with build
settings the host supplies (
yeoRepositoryUrl/yeoUser/yeoPassword, orYEO_REPOSITORY_URL/YEO_USER/YEO_PASSWORD). Nothing is committed; access comes from YEO support. The previous repository block no longer resolves the engine.
Also: Google Play services is required on Android (face detection), and a valid pilot code from YEO is required — contact YEO support.
Upgrading to 0.5.0
- Android repository: put
yeoRepositoryUrl,yeoUserandyeoPasswordin~/.gradle/gradle.properties(or export theYEO_*variables for CI), and replace the 0.4.x repository block inandroid/app/build.gradlewith the one under Android —npx yeofr-setup androidwrites it. Remove anymavenLocal()added for evaluation. - iOS engine: move the YEOFR Swift Package in your app target to exact
version
0.11.0. - Liveness: read
face.isLive(andface.framingfor hints); stop readinglivenessGenuine; never thresholdconfidence. - Re-enrolment: plan a one-time re-enrolment after upgrading; a refused
stored gallery leaves the engine unenrolled and the stale file on disk until
the next
saveTrackerToDisk. - iOS enrolment flow: if your UI prompted a pose walk on iOS, expect a
single
frontcapture there now.
Upgrading to 0.4.5 (iOS engine 0.7.10)
One iOS behaviour change, and one thing hosts can now stop doing:
- Enrolment is single-identity: a capture replaces the previous one. Setting
enrolNamefor a second person used to leave the first still enrolled and still recognised, and graded the second person against the first person's stored face — so the new person was often never recognised. Exactly one identity is now enrolled at a time. Hosts that expected a gallery of several people will keep only the most recent. - Cancelling a capture no longer needs cleanup. Clearing
enrolNamemid-capture cancels the walk and restores the previously enrolled identity. Before, the capture stayed latched and every later attempt failed with "Enrolment already in progress" until the camera was torn down, so hosts had to restore or clear the tracker themselves — that workaround is no longer needed and can be removed.
Upgrading from 0.3.x
Three things changed for iOS hosts, all of which need action:
- The engine is no longer vendored.
ios/YEOFR.xcframeworkis gone from the package; add the Swift Package below to your app target or the bridge will not compile. - Minimum iOS is now 17.0, up from 15.1 — raise
platform :iosin yourPodfileandIPHONEOS_DEPLOYMENT_TARGETon your app target. - Simulator builds need
EXCLUDED_ARCHS[sdk=iphonesimulator*] = x86_64(see below). Apple-silicon Macs only; there is no Intel simulator slice.
The JS API also changed, on both platforms:
createTracker()/freeTracker()are gone. The SDK owns the tracker's lifetime since activation was introduced; there is nothing to create or free.- Return codes are strings, and failures resolve instead of rejecting.
loadTracker/clearTracker/enrollImageresolve"OK"on success and a platform failure string otherwise (iOS its Swift case names, Android"error(-5)") — they no longer resolve numbers, and no longer reject on an SDK failure. Oldcatch-based handling (iOS) and=== 0checks (Android) silently invert: migrate them toisOK(await loadTracker(...)). enroll(faceID, name)is gone. Camera enrolment runs behind the bridge on both platforms: setenrolNameon<YeofrCamera>and wait forregistered.- Every SDK call now requires
activate()first and rejectsnot_activateduntil it resolves.
iOS autolinking is also fixed — in 0.3.x the CLI reported ios: null and never
installed the pod at all.
Install
npm i @yeomessagingcom/react-native-yeofr
npx yeofr-setup # iOS Swift Package + Android Repsy repo + pod install
npx yeofr-setup doctor # verifies every stepFull walkthrough, both platforms, including the manual equivalents of what the script does: docs/REACT-NATIVE-INTEGRATION.md.
The module API works with the New Architecture left on (the RN template
default). On Android the camera view works there too: it is a legacy view
manager served by React Native's interop layer, and its events go through the
UIManager event dispatcher, so nothing is logged per frame. On iOS the camera
view (YeofrCameraView, a legacy RCTViewManager) still needs the old
architecture: set RCT_NEW_ARCH_ENABLED=0 only if you use the camera screen —
see Verified.
iOS
The npm package ships only the RN bridge sources — the engine is not vendored. Add it to your app target in Xcode once:
- open
ios/<YourApp>.xcworkspace→ File ▸ Add Package Dependencies… - enter
https://github.com/yeo-messaging/YEOFR-SPM.git, rule Exact Version0.11.0, add theYEOFRlibrary to your app target - Xcode links and embeds it; the CocoaPods bridge target picks the module up from the shared build products directory
Then add the post_install block to your Podfile
and re-run pod install. On Xcode 26 it is required, not a fallback — it
does two things, and each is a hard build failure without it:
- sets
EXCLUDED_ARCHS[sdk=iphonesimulator*] = x86_64on the app and Pods targets. The published xcframework has no Intel simulator slice, so without this a simulator build fails withunable to resolve module dependency: 'YEOFR'. - patches the
fmtpod (see below).
Also raise platform :ios to '17.0' in your Podfile.
Android
Add the YEO repository to your app module — android/app/build.gradle
(npx yeofr-setup android writes this block):
repositories {
mavenCentral()
google()
maven {
name = "YEO"
url = uri(providers.gradleProperty("yeoRepositoryUrl").orElse(providers.environmentVariable("YEO_REPOSITORY_URL")).getOrElse(""))
credentials {
username = providers.gradleProperty("yeoUser").orElse(providers.environmentVariable("YEO_USER")).getOrElse("")
password = providers.gradleProperty("yeoPassword").orElse(providers.environmentVariable("YEO_PASSWORD")).getOrElse("")
}
}
}The repository is private and its URL is not part of this package. Put the
URL and credentials YEO issued in ~/.gradle/gradle.properties (or an
uncommitted gradle.properties of your own):
yeoRepositoryUrl=<the repository URL YEO gave you>
yeoUser=<your user>
yeoPassword=<your password>For CI, set YEO_REPOSITORY_URL, YEO_USER and YEO_PASSWORD in the
environment instead. Never commit any of them. The bridge's own build fails
with a message naming these when the URL is missing; a missing or wrong login
shows as 401 from the repository.
This is not optional and npm i cannot do it for you. Gradle resolves a
project dependency's transitive artifacts against the consuming project's
repositories, so the repositories {} block inside this package's own
android/build.gradle never applies to your :app. Without the block above
the build fails with Could not find com.yeomessaging:yeofr-android:0.2.29.
Putting it in the root project's buildscript.repositories does not work
either — that only feeds the Gradle classpath.
Declare the camera permission yourself
This package's manifest declares no permissions. The frame API works with
no camera at all, so whether your app carries a dangerous permission on its
Play listing is your call, not this library's. If you mount YeofrCamera, add
to your own AndroidManifest.xml:
<uses-permission android:name="android.permission.CAMERA" />Without it, camera binding fails at the OS level. And declaring it is not
enough — requesting the runtime grant is also your job. The package never
prompts. Mount YeofrCamera without the grant and it reports
{ type: 'error', failure: 'permissionDenied' } through onEvent and draws
nothing; ask with PermissionsAndroid.request first, as
example/src/CameraDemoScreen.tsx does.
If your app is nothing but a recognition screen, also mark the feature required so it cannot install on a camera-less device:
<uses-feature android:name="android.hardware.camera" android:required="true" />16 KB page size (Google Play)
Google Play requires apps targeting Android 15 or later to support 16 KB memory
pages: every native library in the APK or App Bundle must be 16 KB aligned.
From 0.5.2 the bridge pins yeofr-android 0.2.29, whose TensorFlow Lite
runtime (the LiteRT artifacts, com.google.ai.edge.litert) ships 16 KB
aligned libraries. To keep your build compliant:
Let the bridge bring in the engine. If your app declares
com.yeomessaging:yeofr-androiditself, declare0.2.29.Do not add TensorFlow Lite 2.14 of your own.
org.tensorflow:tensorflow-lite2.14 (and its-gpu,-gpu-apiand-supportartifacts) carries 4 KB aligned native libraries and brings the rejection back. If your app uses TensorFlow Lite directly, use the LiteRT artifacts (com.google.ai.edge.litert:litert,litert-gpu,litert-gpu-api) instead.Build with Android Gradle Plugin 8.5.1 or later, which packages native libraries 16 KB aligned.
Check the APK you upload. Android Studio's APK Analyzer flags libraries that are not 16 KB aligned, or run
zipalignfrom the Android build tools:zipalign -c -P 16 -v 4 app-release.apk # ends with "Verification successful"The check covers every native library in the app, including those of React Native and your other packages. The requirement applies to the 64-bit ABIs (
arm64-v8a,x86_64).
Verified
Against a stock React Native 0.81.4 project on Xcode 26, installed from the packed tarball, with the New Architecture left on (the template default):
| Target | 0.5.0 status |
|---|---|
| Android emulator (API 36, arm64) | the example built against the engine resolved from YEO's repository installs, activates and reports engine 0.2.28 — see ANDROID-0.2.28-CHECKS.md for the full run |
| Samsung SM-G998B (S21 Ultra) | verified on engine 0.2.28 (the same AAR bytes, then resolved from a local Maven cache): builds, installs, activates, enrols and recognises a real face with isLive: true; a photo of the same face on another phone's screen is recognised but reads isLive: false on every frame (0 trusted) |
| iOS | the bridge and the example compile against YEOFR-SPM 0.11.0 (simulator target, compile only); no device or simulator run on 0.11.0 yet |
0.5.2 changes only the engine's runtime libraries (0.2.29 has no API or
behaviour change from 0.2.28) and how the Android camera view delivers its
events. The example built against engine 0.2.29 passes
zipalign -c -P 16, and every 64-bit native library in it, the engine's
runtime included, has 16 KB aligned segments; the device runs above were not
repeated on 0.2.29.
Earlier releases were verified on other hardware (iPhone 17 Pro Max on 0.7.10, Samsung SM-A155F on 0.1.24); those runs predate 0.5.0's engines and are not re-verified.
The module API works under bridgeless — example/ios/Podfile sets
RCT_NEW_ARCH_ENABLED=0 only for the camera view (YeofrCameraView is a legacy
RCTViewManager). You need that opt-out only if you use the camera screen, and
only on iOS: the Android camera view runs under bridgeless, through the
legacy-view-manager interop, and dispatches its events on the UIManager event
dispatcher (verified on a stock React Native 0.88 app with the New Architecture
on, and on the RN 0.81.4 example in both architectures).
Xcode 26 and the fmt pod
Not caused by this package, but every React Native 0.81 app hits it on Xcode 26 and it looks like a YEOFR failure because it surfaces during the same build:
Pods/fmt/include/fmt/format-inl.h: error: call to consteval function
'fmt::basic_format_string<...>' is not a constant expressionfmt 11.0.2 already disables its consteval path for the compilers it knows
are broken; Xcode 26's clang is not on that list. The block below forces the
same branch by patching fmt/base.h in place, and raises if the patch stops
applying rather than silently handing you back the original compile error. Drop
it once React Native ships a newer fmt.
The post_install block
Paste into your Podfile's target, alongside the react_native_post_install
call you already have:
# No Intel simulator slice in the xcframework.
installer.pods_project.targets.each do |t|
t.build_configurations.each do |bc|
bc.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '17.0'
bc.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'x86_64'
end
end
installer.aggregate_targets.map(&:user_project).uniq.each do |proj|
proj.targets.each do |t|
t.build_configurations.each do |bc|
bc.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'x86_64'
end
end
proj.save
end
# Xcode 26 clang rejects fmt 11.0.2's consteval path.
base_h = File.join(installer.sandbox.root, 'fmt', 'include', 'fmt', 'base.h')
raise "fmt patch: #{base_h} not found — has the fmt pod moved?" unless File.exist?(base_h)
src = File.read(base_h)
needle = "#if !defined(__cpp_lib_is_constant_evaluated)\n# define FMT_USE_CONSTEVAL 0"
marker = "// Xcode 26 clang rejects fmt's consteval path"
unless src.include?(marker) # already patched: `pod install` re-runs on a patched tree
unless src.include?(needle)
raise "fmt patch: the FMT_USE_CONSTEVAL branch is not where we expect in " \
"#{base_h}. Check the pinned fmt version before removing this patch."
end
File.chmod(0644, base_h) # CocoaPods checks pod sources out read-only
File.write(base_h, src.sub(needle, "#if 1 #{marker}\n# define FMT_USE_CONSTEVAL 0"))
endLicensing
This package and the engine it integrates are commercial — see LICENSE.
Shipping it in a product requires a licence agreement, and a licence covers
only the applications it names. Email [email protected] to obtain a
licence and the .yeolicense file to pass to activate.
Bumping npm module version:
- update s.version in podspec with the new version number
- update "version" in package.json with the new version number
if the iOS engine needs updating:
- cut a YEOFR-SPM release from
the engine branch of YEOFRSDK that this package tracks (never from
main) - bump the package requirement in
example/ios/YeofrDemo.xcodeproj(Xcode: package dependency → exact version) and re-resolve - update the version in the table above and in the install steps
for Android, bump com.yeomessaging:yeofr-android in android/build.gradle.
Publishing:
- deprecate previous version (if required) (NB 0.3.13 is an example):
npm deprecate @yeomessagingcom/[email protected] "Deprecated"- tag with the latest version (
X.Y.Zbelow is a placeholder — use the real next version of the npm module):
git tag X.Y.Z
git push --tags- publish
npm publish --access public