Belajar NativePHP - Konfigurasi Aplikasi

#Pendahuluan

Setelah di episode 3 kita membuat project pertama dan menjalankannya di simulator/emulator, pada episode ini kita dalami konfigurasi aplikasi. Konfigurasi ini menentukan bagaimana aplikasi kalian di-identifikasi di store, bagaimana tampilannya saat pertama dibuka, dan bagaimana environment variables di-bundle ke dalam aplikasi.

Konfigurasi yang benar adalah prasyarat sebelum build distribusi. App identifier yang salah bisa menolak submission ke App Store/Play Store, dan environment yang tidak ter-bundle bisa menyebabkan aplikasi crash saat runtime.

#App Identifier dan Identitas

#iOS: Bundle Identifier

Bundle ID adalah identitas unik aplikasi di ekosistem Apple. Format standar menggunakan reverse domain: com.perusahaan.namaapp. Bundle ID ini tidak bisa diubah setelah aplikasi terdaftar di App Store Connect.

<?php
 
return [
    'ios' => [
        'bundle_id' => env('NATIVEPHP_IOS_BUNDLE', 'com.mycompany.myapp'),
        'display_name' => env('NATIVEPHP_IOS_DISPLAY', 'My App'),
        'version' => env('NATIVEPHP_APP_VERSION', '1.0.0'),
        'build_number' => env('NATIVEPHP_IOS_BUILD', '1'),
        'minimum_os_version' => '18.0',
    ],
];

#Android: Package Name

Package name di Android menggunakan format yang sama — reverse domain. Package ini juga menjadi ID unik di Google Play Console.

<?php
 
return [
    'android' => [
        'package_name' => env('NATIVEPHP_ANDROID_PACKAGE', 'com.mycompany.myapp'),
        'app_name' => env('NATIVEPHP_ANDROID_NAME', 'My App'),
        'version_code' => env('NATIVEPHP_ANDROID_VERSION_CODE', '1'),
        'min_sdk_version' => '26',
        'target_sdk_version' => '35',
    ],
];

#Environment Variables yang Ter-Bundle

Berbeda dengan aplikasi web yang membaca .env dari server, NativePHP perlu membawa environment variables ke dalam bundle. Ini penting untuk API keys, base URL backend, dan konfigurasi lain yang dibutuhkan saat runtime.

<?php
 
return [
    'environment' => [
        'APP_NAME' => env('APP_NAME', 'NativePHP App'),
        'APP_URL' => env('APP_URL', 'https://api.myapp.com'),
        'API_KEY' => env('MY_API_KEY', ''),
        // Hanya variabel yang didefinisikan di sini yang di-bundle
    ],
];

Karena .env tidak dibundel ke aplikasi (alasan keamanan), kalian mendefinisikan variabel apa saja yang perlu dibawa di config/nativephp.php. Nilai diambil dari .env saat build time dan di-embed ke dalam bundle.

#Ikon dan Splash Screen

#Ikon Aplikasi

Ikon harus sesuai dengan guidelines masing-masing platform. NativePHP menyediakan command untuk generate otomatis:

php artisan native:assets --icon=path/to/icon-1024.png

#Splash Screen

Splash screen ditampilkan saat aplikasi pertama kali dimulai. Di iOS, ini dikelola oleh LaunchScreen.storyboard; di Android, oleh splash.xml dan tema Theme.SplashScreen.

<?php
 
return [
    'splash' => [
        'background_color' => '#ffffff',
        'image' => 'resources/native/splash.png',
        'animation' => true, // fade-in animation
    ],
];

#Orientasi Layar

Kontrol orientasi layar yang didukung aplikasi:

<?php
 
return [
    'ios' => [
        'orientations' => [
            'portrait',
            'landscape-left',
            'landscape-right',
        ],
    ],
    'android' => [
        'screen_orientation' => 'unspecified', // portrait, landscape, atau unspecified
    ],
];

Untuk aplikasi yang portrait-only (paling umum untuk mobile app), cukup set 'portrait' saja. Untuk game atau apps yang membutuhkan landscape, set semua orientasi.

#Status Bar Style

Status bar (bar di atas layar dengan jam, baterai, signal) bisa dikustomisasi:

<?php
 
return [
    'ios' => [
        'status_bar_style' => 'lightContent', // darkContent, lightContent, default
        'status_bar_hidden' => false,
    ],
    'android' => [
        'status_bar_color' => '#ffffff',
        'status_bar_light' => true, // true = teks gelap di background terang
    ],
];

lightContent cocok untuk background gelap (teks putih), darkContent untuk background terang (teks hitam). Pilihan ini harus konsisten dengan desain UI kalian.

#Praktik: Kustomisasi Identitas Lengkap

Mari kita ubah konfigurasi aplikasi menjadi sesuatu yang lebih spesifik:

<?php
 
return [
    'name' => 'Todo Native',
    'id' => 'com.mycompany.todonative',
    'version' => '1.0.0',
 
    'environment' => [
        'APP_NAME' => 'Todo Native',
        'APP_URL' => env('APP_URL', 'https://api.todonative.com'),
        'MIX_PUSHER_APP_KEY' => env('PUSHER_APP_KEY', ''),
    ],
 
    'ios' => [
        'bundle_id' => env('NATIVEPHP_IOS_BUNDLE', 'com.mycompany.todonative'),
        'display_name' => 'Todo Native',
        'minimum_os_version' => '18.0',
        'orientations' => ['portrait'],
        'status_bar_style' => 'darkContent',
    ],
 
    'android' => [
        'package_name' => env('NATIVEPHP_ANDROID_PACKAGE', 'com.mycompany.todonative'),
        'app_name' => 'Todo Native',
        'min_sdk_version' => '26',
        'target_sdk_version' => '35',
        'screen_orientation' => 'portrait',
    ],
];

Setelah mengubah konfigurasi, jalankan ulang:

php artisan native:run

Verifikasi bahwa nama aplikasi, ikon, dan status bar sudah sesuai di simulator/emulator.

#Penutup

Inti yang harus dibawa pulang:

• App identifier (Bundle ID untuk iOS, Package Name untuk Android) harus unik dan konsisten.
• Environment variables didefinisikan di nativephp.php dan di-bundle ke dalam aplikasi.
• Ikon & splash screen di-generate dengan native:assets dan harus sesuai guidelines platform.
• Orientasi & status bar dikonfigurasi sesuai kebutuhan desain aplikasi.
• Selalu gunakan environment variables untuk perbedaan dev/staging/production.

Di episode 5 selanjutnya, kita akan membahas UI dengan Blade & Livewire — cara membangun antarmuka pengguna menggunakan Blade template, Livewire components, dan Tailwind CSS di dalam WebView (pre-v4) atau native rendering (v4 SuperNative). Sampai jumpa di episode 5!