Skip to content

Commit f0beed1

Browse files
shanerbaner82PeteBishwhipSRWieZsimonhamp
authored
📚 Mobile v1.1 Documentation Updates (#178)
* Updates some of the docs for mobile * Updates ordering for docs * updates doc * 📚 Update mobile v1.1 documentation structure and content - Reorganize v1.1 documentation with new APIs and concepts sections - Add comprehensive database security guidance covering API-first architecture, Laravel Sanctum integration, and SecureStorage best practices - Simplify Haptics API documentation to essential examples and usage patterns - Add Windows performance tip for faster composer installs during compilation - Improve geolocation API documentation with detailed event handling - Update installation guide with platform-specific optimizations - Restructure v1.1 content hierarchy for better developer experience * Resolve merge conflicts with main branch - Merge installation.md: preserve platform requirements from main + Windows performance tip - Update ShowDocumentationController.php with latest changes * Update resources/views/docs/mobile/1/apis/camera.md Co-authored-by: Peter Bishop <[email protected]> * More docs updates * Update mobile documentation with enhanced deep links, push notifications, and database seeding - Enhanced deep links documentation with comprehensive platform-specific setup, domain verification, and NFC integration - Expanded push notifications docs with FCM implementation, platform-specific configurations, and data payload handling - Added database seeding section explaining how to use migrations for initial data setup - Updated various documentation files with improved clarity and additional configuration examples - Fixed broken links and improved navigation structure * Update Dialog API documentation for new alert implementation - Updated alert() method signature to use 3 parameters (title, message, buttons array) - Changed buttons parameter from complex objects to simple string arrays - Updated ButtonPressed event to pass both index and label parameters - Replaced all example code to use new simplified API - Added button positioning documentation (negative, neutral, positive) - Removed old button style configurations - Added practical examples for 1, 2, and 3 button scenarios * Add Browser API documentation for in-app browser functionality - Added new browser.md documentation for Browser::inApp() method - Documented OAuth authentication use cases with deep link integration - Included platform-specific behavior for iOS and Android - Added complete example showing Livewire component implementation - Covered security considerations and best practices - Explained integration with deep links for complete OAuth flows * Update resources/views/docs/mobile/1/the-basics/icu-support.md Co-authored-by: Eser DENIZ <[email protected]> * Update resources/views/docs/mobile/1/apis/browser.md Co-authored-by: Eser DENIZ <[email protected]> * Update mobile documentation with API improvements and platform notes - Add Android-only notes for ICU support across documentation - Update Dialog API documentation with new alert implementation - Enhance Geolocation API documentation - Improve API overview and navigation - Update Push Notifications API documentation - Enhance Secure Storage API documentation - Add database documentation improvements - Update CI/CD packaging commands with platform limitations - Ensure consistent platform availability information across docs * Simplify versioning documentation with Laravel-inspired approach - Reduce length by 70% while maintaining all essential information - Add explicit semantic versioning reference and link - Adopt Laravel's direct, confident tone and structure - Focus on practical information developers need - Remove verbose examples and repetitive explanations - Maintain mobile-specific versioning concepts (patch vs minor releases) - Keep OTA compatibility messaging and composer integration guidance * Update Browser API documentation with new methods and improved structure - Add system() method for opening URLs in device's default browser - Add auth() method for OAuth authentication flows with nativephp:// handling - Update inApp() method description with platform-specific details - Add comprehensive use cases for each browser method - Include platform behavior notes for iOS and Android implementations - Remove redundant sections and streamline documentation - Update examples to demonstrate all three browser methods * polish (#182) --------- Co-authored-by: Peter Bishop <[email protected]> Co-authored-by: Eser DENIZ <[email protected]> Co-authored-by: Simon Hamp <[email protected]>
1 parent d491237 commit f0beed1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1971
-670
lines changed

‎app/Http/Controllers/ShowDocumentationController.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,6 @@ public function __invoke(Request $request, string $platform, string $version, ?s
4646
} catch (InvalidArgumentException $e) {
4747
return $this->redirectToFirstNavigationPage($navigation, $page);
4848
}
49-
5049
SEOTools::setTitle($pageProperties['title'].' - NativePHP '.$platform.' v'.$version);
5150
SEOTools::setDescription(Arr::exists($pageProperties, 'description') ? $pageProperties['description'] : '');
5251

@@ -65,7 +64,8 @@ protected function getPageProperties($platform, $version, $page = null): array
6564
$pageProperties = $document->matter();
6665

6766
$versionProperties = YamlFrontMatter::parseFile(resource_path("views/docs/{$platform}/{$version}/_index.md"));
68-
$pageProperties = array_merge($pageProperties, $versionProperties->matter());
67+
68+
$pageProperties = array_merge($versionProperties->matter(), $pageProperties);
6969

7070
$pageProperties['platform'] = $platform;
7171
$pageProperties['version'] = $version;

‎resources/views/docs/mobile/1/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Mobile
3+
order: 1
4+
---

‎resources/views/docs/mobile/1/apis/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: APIs
3+
order: 4
4+
---

‎resources/views/docs/mobile/1/apis/biometrics.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Biometrics
3+
order: 100
4+
---
5+
6+
## Overview
7+
8+
The Biometrics API allows you to authenticate users using their device's biometric sensors like Face ID, Touch ID, or
9+
fingerprint scanners.
10+
11+
```php
12+
use Native\Mobile\Facades\Biometrics;
13+
```
14+
15+
## Methods
16+
17+
### `promptForBiometricID()`
18+
19+
Prompts the user for biometric authentication.
20+
21+
```php
22+
use Native\Mobile\Facades\Biometrics;
23+
24+
Biometrics::promptForBiometricID();
25+
```
26+
27+
## Events
28+
29+
### `Completed`
30+
31+
Fired when biometric authentication completes (success or failure).
32+
33+
```php
34+
use Livewire\Attributes\On;
35+
use Native\Mobile\Events\Biometric\Completed;
36+
37+
#[On('native:'.Completed::class)]
38+
public function handleBiometricAuth(bool $success)
39+
{
40+
if ($success) {
41+
// User authenticated successfully
42+
$this->unlockSecureFeature();
43+
} else {
44+
// Authentication failed
45+
$this->showErrorMessage();
46+
}
47+
}
48+
```
49+
50+
## Platform Support
51+
52+
- **iOS:** Face ID, Touch ID
53+
- **Android:** Fingerprint, Face unlock, other biometric methods
54+
- **Fallback:** System authentication (PIN, password, pattern)
55+
56+
## Security Notes
57+
58+
- Biometric authentication provides **convenience**, not absolute security
59+
- Always combine with other authentication factors for sensitive operations
60+
- Consider implementing session timeouts for unlocked states
61+
- Users can potentially bypass biometrics if their device is compromised

‎resources/views/docs/mobile/1/apis/browser.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Browser
3+
order: 150
4+
---
5+
6+
## Overview
7+
8+
The Browser API provides three methods for opening URLs, each designed for specific use cases:
9+
in-app browsing, system browser navigation, and web authentication flows.
10+
11+
```php
12+
use Native\Mobile\Facades\Browser;
13+
```
14+
15+
## Methods
16+
17+
### `inApp()`
18+
19+
Opens a URL in an embedded browser within your app using Custom Tabs (Android) or SFSafariViewController (iOS).
20+
21+
```php
22+
Browser::inApp('https://nativephp.com/mobile');
23+
```
24+
25+
### `system()`
26+
27+
Opens a URL in the device's default browser app, leaving your application entirely.
28+
29+
```php
30+
Browser::system('https://nativephp.com/mobile');
31+
```
32+
33+
### `auth()`
34+
35+
Opens a URL in a specialized authentication browser designed for OAuth flows with automatic `nativephp://` redirect handling.
36+
37+
```php
38+
Browser::auth('https://provider.com/oauth/authorize?client_id=123&redirect_uri=nativephp://127.0.0.1/auth/callback');
39+
```
40+
41+
## Use Cases
42+
43+
### When to Use Each Method
44+
45+
**`inApp()`** - Keep users within your app experience:
46+
- Documentation, help pages, terms of service
47+
- External content that relates to your app
48+
- When you want users to easily return to your app
49+
50+
**`system()`** - Full browser experience needed:
51+
- Complex web applications
52+
- Content requiring specific browser features
53+
- When users need bookmarking or sharing capabilities
54+
55+
**`auth()`** - OAuth authentication flows:
56+
- Login with WorkOS, Auth0, Google, Facebook, etc.
57+
- Secure authentication with automatic redirects
58+
- Isolated browser session for security

‎resources/views/docs/mobile/1/apis/camera.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Camera
3+
order: 200
4+
---
5+
6+
## Overview
7+
8+
The Camera API provides access to the device's camera for taking photos and selecting images from the gallery.
9+
10+
```php
11+
use Native\Mobile\Facades\Camera;
12+
```
13+
14+
## Methods
15+
16+
### `getPhoto()`
17+
18+
Opens the camera interface to take a photo.
19+
20+
```php
21+
Camera::getPhoto();
22+
```
23+
24+
### `pickImages()`
25+
26+
Opens the gallery/photo picker to select existing images.
27+
28+
**Parameters:**
29+
- `string $media_type` - Type of media to pick: `'all'`, `'images'`, `'videos'` (default: `'all'`)
30+
- `bool $multiple` - Allow multiple selection (default: `false`)
31+
32+
**Returns:** `bool` - `true` if picker opened successfully
33+
34+
```php
35+
// Pick a single image
36+
Camera::pickImages('images', false);
37+
38+
// Pick multiple images
39+
Camera::pickImages('images', true);
40+
41+
// Pick any media type
42+
Camera::pickImages('all', true);
43+
```
44+
45+
## Events
46+
47+
### `PhotoTaken`
48+
49+
Fired when a photo is taken with the camera.
50+
51+
**Payload:** `string $path` - File path to the captured photo
52+
53+
```php
54+
use Livewire\Attributes\On;
55+
use Native\Mobile\Events\Camera\PhotoTaken;
56+
57+
#[On('native:'.PhotoTaken::class)]
58+
public function handlePhotoTaken(string $path)
59+
{
60+
// Process the captured photo
61+
$this->processPhoto($path);
62+
}
63+
```
64+
65+
### `MediaSelected`
66+
67+
Fired when media is selected from the gallery.
68+
69+
**Payload:** `array $media` - Array of selected media items
70+
71+
```php
72+
use Livewire\Attributes\On;
73+
use Native\Mobile\Events\Gallery\MediaSelected;
74+
75+
#[On('native:'.MediaSelected::class)]
76+
public function handleMediaSelected($success, $files, $count)
77+
{
78+
foreach ($files as $file) {
79+
// Process each selected media item
80+
$this->processMedia($file);
81+
}
82+
}
83+
```
84+
85+
## Notes
86+
87+
- The first time your app requests camera access, users will be prompted for permission
88+
- If permission is denied, camera functions will fail silently
89+
- Captured photos are stored in the app's temporary directory
90+
- File formats are platform-dependent (typically JPEG)

‎resources/views/docs/mobile/1/apis/dialog.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: Dialog
3+
order: 300
4+
---
5+
6+
## Overview
7+
8+
The Dialog API provides access to native UI elements like alerts, toasts, and sharing interfaces.
9+
10+
```php
11+
use Native\Mobile\Facades\Dialog;
12+
```
13+
14+
## Methods
15+
16+
### `alert()`
17+
18+
Displays a native alert dialog with customizable buttons.
19+
20+
**Parameters:**
21+
- `string $title` - The alert title
22+
- `string $message` - The alert message
23+
- `array $buttons` - Array of button labels (max 3 buttons)
24+
25+
**Button Positioning:**
26+
- **1 button** - Positive (OK/Confirm)
27+
- **2 buttons** - Negative (Cancel) + Positive (OK/Confirm)
28+
- **3 buttons** - Negative (Cancel) + Neutral (Maybe) + Positive (OK/Confirm)
29+
30+
```php
31+
Dialog::alert(
32+
'Confirm Action',
33+
'Are you sure you want to delete this item?',
34+
['Cancel', 'Delete']
35+
);
36+
```
37+
38+
### `toast()`
39+
40+
Displays a brief toast notification message.
41+
42+
43+
**Parameters:**
44+
- `string $message` - The message to display
45+
46+
```php
47+
Dialog::toast('Item saved successfully!');
48+
```
49+
50+
#### Good toast messages
51+
52+
- Short and clear
53+
- Great for confirmations and status updates
54+
- Don't rely on them for critical information
55+
- Avoid showing multiple toasts in quick succession
56+
57+
### `share()`
58+
59+
Opens the native sharing interface.
60+
61+
**Parameters:**
62+
- `string $title` - The share dialog title
63+
- `string $text` - Text content to share
64+
- `string $url` - URL to share
65+
66+
```php
67+
Dialog::share(
68+
'Check this out!',
69+
'I found this amazing Laravel package for mobile development',
70+
'https://nativephp.com'
71+
);
72+
```
73+
74+
## Events
75+
76+
### `ButtonPressed`
77+
78+
Fired when a button is pressed in an alert dialog.
79+
80+
**Payload:**
81+
- `int $index` - Index of the pressed button (0-based)
82+
- `string $label` - Label/text of the pressed button
83+
84+
```php
85+
use Livewire\Attributes\On;
86+
use Native\Mobile\Events\Alert\ButtonPressed;
87+
88+
#[On('native:'.ButtonPressed::class)]
89+
public function handleAlertButton($index, $label)
90+
{
91+
switch ($index) {
92+
case 0:
93+
// First button (usually Cancel)
94+
Dialog::toast("You pressed '{$label}'");
95+
break;
96+
case 1:
97+
// Second button (usually OK/Confirm)
98+
$this->performAction();
99+
Dialog::toast("You pressed '{$label}'");
100+
break;
101+
}
102+
}
103+
```

0 commit comments

Comments
 (0)