Permissions & Dependencies

Platform Configuration#

Platform-specific settings are grouped under android and ios keys in your manifest. This keeps all configuration for each platform together:

Copied!

{
    "android": {
        "permissions": [...],
        "dependencies": {...},
        "repositories": [...],
        "activities": [...],
        "services": [...]
    },
    "ios": {
        "info_plist": {...},
        "dependencies": {...}
    }
}

{
    "android": {
        "permissions": [...],
        "dependencies": {...},
        "repositories": [...],
        "activities": [...],
        "services": [...]
    },
    "ios": {
        "info_plist": {...},
        "dependencies": {...}
    }
}

Permissions#

Android Permissions#

List Android permissions as strings under android.permissions:

Copied!

{
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.RECORD_AUDIO",
            "android.permission.ACCESS_FINE_LOCATION"
        ]
    }
}

{
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.RECORD_AUDIO",
            "android.permission.ACCESS_FINE_LOCATION"
        ]
    }
}

These are added to the app's AndroidManifest.xml at build time.

See the Android Manifest.permission reference for a complete list of available permissions.

iOS Info.plist Entries#

iOS requires usage descriptions for each permission, plus any API keys or configuration tokens your plugin needs. Provide these as key-value pairs under ios.info_plist:

Copied!

{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning",
            "NSMicrophoneUsageDescription": "This app records audio for transcription",
            "NSLocationWhenInUseUsageDescription": "This app needs your location",
            "MBXAccessToken": "${MAPBOX_ACCESS_TOKEN}"
        }
    }
}

{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning",
            "NSMicrophoneUsageDescription": "This app records audio for transcription",
            "NSLocationWhenInUseUsageDescription": "This app needs your location",
            "MBXAccessToken": "${MAPBOX_ACCESS_TOKEN}"
        }
    }
}

These are merged into the app's Info.plist. You can include:

Permission usage descriptions (NS*UsageDescription keys)
API tokens and configuration keys
Any other Info.plist entries your plugin requires

See the Apple Information Property List reference for all available keys.

Use ${ENV_VAR} placeholders for sensitive values like API tokens.

Localizing Info.plist Strings#

Values in ios.info_plist are written to the bundle's Info.plist and shown by iOS in whichever language they were authored. To translate them for users on other system languages, add a sibling ios.info_plist_localizations block. Each key is a BCP 47 locale code (e.g. nl, fr, zh-Hans, pt-BR) and its value mirrors the info_plist shape:

Copied!

{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning"
        },
        "info_plist_localizations": {
            "nl": {
                "NSCameraUsageDescription": "Deze app gebruikt de camera om te scannen"
            },
            "fr": {
                "NSCameraUsageDescription": "Cette application utilise la caméra pour le scan"
            }
        }
    }
}

{
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "This app uses the camera for scanning"
        },
        "info_plist_localizations": {
            "nl": {
                "NSCameraUsageDescription": "Deze app gebruikt de camera om te scannen"
            },
            "fr": {
                "NSCameraUsageDescription": "Cette application utilise la caméra pour le scan"
            }
        }
    }
}

At build time NativePHP writes one {locale}.lproj/InfoPlist.strings file per locale into the host app's iOS project, and iOS picks the right string at runtime based on the user's preferred language. Any key not present in a locale block falls back to the value from info_plist.

App-level overrides set in the host app's config('nativephp.permission_localizations') win over the values declared here — useful when an app developer needs to resolve collisions between plugins that ship localizations for the same key.

Dependencies#

Android Dependencies#

Add Gradle dependencies under android.dependencies:

Copied!

{
    "android": {
        "dependencies": {
            "implementation": [
                "com.google.mlkit:face-detection:16.1.5",
                "org.tensorflow:tensorflow-lite:2.13.0"
            ]
        }
    }
}

{
    "android": {
        "dependencies": {
            "implementation": [
                "com.google.mlkit:face-detection:16.1.5",
                "org.tensorflow:tensorflow-lite:2.13.0"
            ]
        }
    }
}

These are added to the app's build.gradle.kts during compilation. You can use any Gradle dependency type:

implementation — Standard dependency
api — Exposed to consumers
compileOnly — Compile-time only
runtimeOnly — Runtime only

iOS Dependencies#

CocoaPods

For CocoaPods dependencies, use the pods array:

Copied!

{
    "ios": {
        "dependencies": {
            "pods": [
                {"name": "GoogleMLKit/FaceDetection", "version": "~> 4.0"},
                {"name": "TensorFlowLiteSwift", "version": "~> 2.13"}
            ]
        }
    }
}

{
    "ios": {
        "dependencies": {
            "pods": [
                {"name": "GoogleMLKit/FaceDetection", "version": "~> 4.0"},
                {"name": "TensorFlowLiteSwift", "version": "~> 2.13"}
            ]
        }
    }
}

Each pod object accepts:

name — The pod name (required)
version — Version constraint (optional, e.g., ~> 4.0, >= 1.0)

NativePHP generates a Podfile and runs pod install during the iOS build process.

Swift Packages

For Swift Package Manager dependencies:

Copied!

{
    "ios": {
        "dependencies": {
            "swift_packages": [
                {
                    "url": "https://github.com/example/SomePackage",
                    "version": "1.0.0"
                }
            ]
        }
    }
}

{
    "ios": {
        "dependencies": {
            "swift_packages": [
                {
                    "url": "https://github.com/example/SomePackage",
                    "version": "1.0.0"
                }
            ]
        }
    }
}

Custom Repositories#

Some dependencies require private or non-standard Maven repositories (like Mapbox). Add them under android.repositories:

Copied!

{
    "android": {
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    }
}

{
    "android": {
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    }
}

Repository configuration:

url — The repository URL (required)
credentials — Optional authentication
- username — Username or token name
- password — Password or token (supports ${ENV_VAR} placeholders)

These are added to the app's settings.gradle.kts.

Full Example#

Here's a complete manifest for an ML plugin that uses Mapbox maps:

Copied!

{
    "name": "vendor/ml-maps-plugin",
    "namespace": "MLMaps",
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.ACCESS_FINE_LOCATION"
        ],
        "dependencies": {
            "implementation": [
                "com.google.mlkit:object-detection:17.0.0",
                "com.mapbox.maps:android:11.0.0"
            ]
        },
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for real-time object detection",
            "NSLocationWhenInUseUsageDescription": "Location is used to display your position on the map",
            "MBXAccessToken": "${MAPBOX_PUBLIC_TOKEN}"
        },
        "dependencies": {
            "pods": [
                {"name": "MapboxMaps", "version": "~> 11.0"}
            ]
        }
    },
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "MAPBOX_PUBLIC_TOKEN": {
            "description": "Mapbox public access token for runtime API calls",
            "required": true
        }
    }
}

{
    "name": "vendor/ml-maps-plugin",
    "namespace": "MLMaps",
    "android": {
        "permissions": [
            "android.permission.CAMERA",
            "android.permission.ACCESS_FINE_LOCATION"
        ],
        "dependencies": {
            "implementation": [
                "com.google.mlkit:object-detection:17.0.0",
                "com.mapbox.maps:android:11.0.0"
            ]
        },
        "repositories": [
            {
                "url": "https://api.mapbox.com/downloads/v2/releases/maven",
                "credentials": {
                    "username": "mapbox",
                    "password": "${MAPBOX_DOWNLOADS_TOKEN}"
                }
            }
        ]
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for real-time object detection",
            "NSLocationWhenInUseUsageDescription": "Location is used to display your position on the map",
            "MBXAccessToken": "${MAPBOX_PUBLIC_TOKEN}"
        },
        "dependencies": {
            "pods": [
                {"name": "MapboxMaps", "version": "~> 11.0"}
            ]
        }
    },
    "secrets": {
        "MAPBOX_DOWNLOADS_TOKEN": {
            "description": "Mapbox SDK download token from mapbox.com/account/access-tokens",
            "required": true
        },
        "MAPBOX_PUBLIC_TOKEN": {
            "description": "Mapbox public access token for runtime API calls",
            "required": true
        }
    }
}

Official Plugins & Dev Kit#

Skip the configuration complexity — browse ready-made plugins or get the Dev Kit to build your own. Visit the NativePHP Plugin Marketplace →