242 lines
7.6 KiB
Plaintext
242 lines
7.6 KiB
Plaintext
---
|
|
title: Mobile App Development Setup
|
|
description: Setup guide for Chatwoot mobile app development
|
|
sidebarTitle: Mobile App Setup
|
|
---
|
|
|
|
# Setup guide for mobile app
|
|
|
|
Complete guide to setting up the Chatwoot mobile app for development and contribution.
|
|
|
|
## Installation and setup
|
|
|
|
### Prerequisites
|
|
|
|
Before starting, ensure you have the following installed:
|
|
|
|
- [Node.js](https://nodejs.org/en/download/) (Latest LTS version)
|
|
- [React Native CLI](https://reactnative.dev/docs/environment-setup)
|
|
- [Expo CLI](https://docs.expo.dev/get-started/installation/)
|
|
- [Expo Account](https://expo.dev/signup)
|
|
|
|
<Note>
|
|
To learn more about the most up-to-date instructions, please refer to the guide available [here](https://docs.expo.dev/get-started/set-up-your-environment/).
|
|
</Note>
|
|
|
|
### Clone the repository
|
|
|
|
```bash
|
|
git clone git@github.com:chatwoot/chatwoot-mobile-app.git
|
|
cd chatwoot-mobile-app
|
|
```
|
|
|
|
### Install dependencies
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### Install Expo CLI
|
|
|
|
```bash
|
|
pnpm install -g expo-cli
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Create your environment configuration file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Configure the following environment variables:
|
|
|
|
| Name | Description | Default Value | Required |
|
|
| ---------------------------------------- | ------------------------------------------- | ------------------------ | -------- |
|
|
| EXPO_PUBLIC_CHATWOOT_WEBSITE_TOKEN | Web widget token for in-app support | - | No |
|
|
| EXPO_PUBLIC_CHATWOOT_BASE_URL | Self-hosted installation URL | https://app.chatwoot.com | Yes |
|
|
| EXPO_PUBLIC_JUNE_SDK_KEY | June analytics SDK key | - | No |
|
|
| EXPO_PUBLIC_MINIMUM_CHATWOOT_VERSION | Minimum supported Chatwoot version | - | Yes |
|
|
| EXPO_PUBLIC_SENTRY_DSN | Sentry DSN URL for error reporting | - | No |
|
|
| EXPO_PUBLIC_PROJECT_ID | Expo project identifier | - | Yes |
|
|
| EXPO_PUBLIC_APP_SLUG | Application slug for Expo | - | Yes |
|
|
| EXPO_PUBLIC_SENTRY_PROJECT_NAME | Project name in Sentry | - | No |
|
|
| EXPO_PUBLIC_SENTRY_ORG_NAME | Organization name in Sentry | - | No |
|
|
| EXPO_PUBLIC_IOS_GOOGLE_SERVICES_FILE | Path to iOS Google Services config file | - | No |
|
|
| EXPO_PUBLIC_ANDROID_GOOGLE_SERVICES_FILE | Path to Android Google Services config file | - | No |
|
|
| EXPO_APPLE_ID | Apple Developer account ID | - | No |
|
|
| EXPO_APPLE_TEAM_ID | Apple Developer team ID | - | No |
|
|
| EXPO_STORYBOOK_ENABLED | Enable/disable Storybook | false | No |
|
|
|
|
## Generate the native code
|
|
|
|
```bash
|
|
pnpm generate
|
|
```
|
|
|
|
This command generates native Android and iOS directories using [Prebuild](https://docs.expo.dev/workflow/continuous-native-generation/).
|
|
|
|
<Warning>
|
|
You need to run pre-build if you add a new native dependency to your project or change the project configuration in Expo app config (app.config.ts).
|
|
</Warning>
|
|
|
|
## How to run the app
|
|
|
|
Connect your iPhone/Android device and run the following command to install the app on your device.
|
|
|
|
### iOS Development
|
|
|
|
```bash
|
|
pnpm run:ios
|
|
```
|
|
|
|
### Android Development
|
|
|
|
```bash
|
|
pnpm run:android
|
|
```
|
|
|
|
## Package Installation
|
|
|
|
<Warning>
|
|
Please always install packages using the command `npx expo install package-name` instead of `pnpm install package-name`.
|
|
</Warning>
|
|
|
|
This is crucial for native dependencies because Expo will automatically install the correct compatible version, while pnpm/yarn/npm may install the latest version, which may not be compatible.
|
|
|
|
```bash
|
|
# Correct way to install packages
|
|
npx expo install package-name
|
|
|
|
# Incorrect way (may cause compatibility issues)
|
|
pnpm install package-name
|
|
```
|
|
|
|
## Push notification
|
|
|
|
If you are using the community edition of Chatwoot, you can now use the [official mobile app](https://www.chatwoot.com/mobile-apps) with push notifications without any additional configuration.
|
|
|
|
For more details, please refer to the [push notification documentation](https://www.chatwoot.com/hc/handbook/articles/1687935909-push-notification).
|
|
|
|
## Build & Submit using EAS
|
|
|
|
We use Expo Application Services (EAS) for building, deploying, and submitting the app to app stores. EAS Build and Submit is available to anyone with an Expo account, regardless of whether you pay for EAS or use our Free plan.
|
|
|
|
You can sign up at [Expo EAS](https://expo.dev/eas).
|
|
|
|
### Build the app
|
|
|
|
#### iOS Build
|
|
|
|
```bash
|
|
pnpm run build:ios:local
|
|
```
|
|
|
|
#### Android Build
|
|
|
|
```bash
|
|
pnpm run build:android:local
|
|
```
|
|
|
|
### Submit the app
|
|
|
|
#### iOS Submission
|
|
|
|
```bash
|
|
pnpm submit:ios
|
|
```
|
|
|
|
#### Android Submission
|
|
|
|
```bash
|
|
pnpm submit:android
|
|
```
|
|
|
|
When you run the above command, you will be prompted to provide a path to a local app binary file. Please select the file that you built in the previous step:
|
|
|
|
- **iOS**: `.ipa` file
|
|
- **Android**: `.aab` file
|
|
|
|
<Note>
|
|
It may take a while to complete the submission process. You will see the status of the submission on your terminal.
|
|
</Note>
|
|
|
|
## Troubleshooting
|
|
|
|
<Accordion title="Metro bundler issues">
|
|
**Problem**: Metro bundler fails to start or bundle
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Clear cache and restart
|
|
pnpm clear
|
|
pnpm start --reset-cache
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="iOS build fails">
|
|
**Problem**: iOS build or simulator issues
|
|
|
|
**Solution**:
|
|
- Ensure Xcode is properly installed
|
|
- Check iOS simulator version compatibility
|
|
- Clear derived data in Xcode
|
|
- Restart Metro bundler
|
|
</Accordion>
|
|
|
|
<Accordion title="Android build fails">
|
|
**Problem**: Android build or emulator issues
|
|
|
|
**Solution**:
|
|
- Verify Android Studio setup
|
|
- Check SDK versions and build tools
|
|
- Ensure emulator is running
|
|
- Clear Gradle cache
|
|
</Accordion>
|
|
|
|
<Accordion title="Expo CLI issues">
|
|
**Problem**: Expo commands fail
|
|
|
|
**Solution**:
|
|
```bash
|
|
# Update Expo CLI
|
|
npm install -g @expo/cli@latest
|
|
|
|
# Login to Expo
|
|
expo login
|
|
|
|
# Clear Expo cache
|
|
expo r -c
|
|
```
|
|
</Accordion>
|
|
|
|
## Contributing Guidelines
|
|
|
|
When contributing to the mobile app:
|
|
|
|
1. **Follow coding standards**: Use ESLint and Prettier configurations
|
|
2. **Write tests**: Include unit tests for new features
|
|
3. **Test on both platforms**: Ensure iOS and Android compatibility
|
|
4. **Update documentation**: Document new features and changes
|
|
5. **Check performance**: Monitor app performance impact
|
|
|
|
## Getting Help
|
|
|
|
If you encounter issues:
|
|
|
|
- **Expo Documentation**: [Official Expo Docs](https://docs.expo.dev/)
|
|
- **React Native Documentation**: [React Native Docs](https://reactnative.dev/docs/getting-started)
|
|
- **GitHub Issues**: [Mobile App Issues](https://github.com/chatwoot/chatwoot-mobile-app/issues)
|
|
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)
|
|
|
|
## Useful Resources
|
|
|
|
- **Expo Development**: [https://docs.expo.dev/](https://docs.expo.dev/)
|
|
- **React Native**: [https://reactnative.dev/](https://reactnative.dev/)
|
|
- **EAS Build**: [https://docs.expo.dev/build/introduction/](https://docs.expo.dev/build/introduction/)
|
|
- **EAS Submit**: [https://docs.expo.dev/submit/introduction/](https://docs.expo.dev/submit/introduction/)
|
|
|
|
---
|
|
|
|
Your Chatwoot mobile app development environment is now ready! 📱 |