Install NativeWatch for iOS and Android

The mobile integration has a PHP SDK and a native plugin. Installing Composer dependencies enables the PHP integration; compiling the plugin into your app enables its Swift and Kotlin crash collectors.

#Install and register

Use PHP 8.4 or later within PHP 8 and Laravel 11, 12 or 13. The current plugin manifest requires iOS 17 or later and Android API 26 or later. Some crash sources need newer Android versions.

As of 29 October 2026, zinxan/native-mobile is not listed on public Packagist. These commands require access to the SDK distribution and its zinxan/native-core dependency. Confirm that access before proceeding.

composer require zinxan/native-mobile
php artisan vendor:publish --tag=nativephp-plugins-provider
php artisan native:plugin:register zinxan/native-mobile
php artisan native:plugin:validate vendor/zinxan/native-mobile

Keep your existing NativePHP provider and registered plugins when publishing or updating it. Check that NativeWatch appears in the provider's plugin list.

#Configure reporting before boot

Use the project's real ingest key and explicitly configure the production destination:

NATIVEWATCH_KEY=nw_your_project_key
NATIVEWATCH_URL=https://native.watch
NATIVEWATCH_ENABLED=true
NATIVEWATCH_REQUIRE_CONSENT=true
NATIVEWATCH_ENVIRONMENT=development

Implement privacy and consent. Fresh native installations start denied; grant reporting only after the user's choice and check the boolean result. Keeping NATIVEWATCH_REQUIRE_CONSENT=true also makes ordinary PHP browser previews start denied.

Clear stale development configuration, then rebuild the actual native application using your NativePHP build workflow. For a local run:

php artisan config:clear
php artisan native:run ios

Use php artisan native:run android for Android. Rebuild after plugin upgrades too. A refreshed Blade page, successful Composer install or PHP browser preview cannot verify that new Swift or Kotlin code is in the installed binary.

#Know which failures are collected

PHP reporting covers exceptions reaching Laravel and supported fatal-error collection in the mobile runtime. Web-view JavaScript needs the separate script integration.

On iOS, KSCrash supplies Objective-C exception, Mach exception and signal capture. MetricKit can provide delayed device diagnostics. On Android, the plugin collects uncaught JVM exceptions, plus ANR and native-crash evidence available through ApplicationExitInfo on Android 11 and later. Availability of an exit trace depends on the platform; these mechanisms do not guarantee a report for every termination. See Android's exit-information reference.

Native fatal handlers write local evidence. PHP imports eligible reports after relaunch and delivers them through the outbox. The crashing process does not perform network delivery.

#Verify each path

First check the PHP connection in a consented development environment:

php artisan nativewatch:test

Match its printed UUID to the stored occurrence. This constructed PHP diagnostic does not exercise a native crash, and terminal consent/storage can differ from the installed app.

For native acceptance, use a disposable, fully compiled Release build launched outside the debugger. After opting in, invoke this only from a private test control:

use ZXN\NativeWatch\Mobile\NativeCrashes;

app(NativeCrashes::class)->crashForTest('exception');

Observe process exit, relaunch and match the resulting event's build, mechanism and timestamp. Repeat with 'fatal'. Remove crash controls before shipping. ANR, NDK and MetricKit paths require their own checks; one successful crash does not establish all mechanisms.

#Complete build verification

Check denied and withdrawn consent as well as enabled reporting. Verify offline delivery on actual hardware. Physical-iPhone flight-mode acceptance remains deferred in the current project evidence; automated tests and simulator results do not replace it.

Upload the exact Release dSYMs using iOS symbolication. Keep the private upload token in CI, outside the packaged app.