# twilio-chat-js-cordova-example

**Repository Path**: mirrors_twilio/twilio-chat-js-cordova-example

## Basic Information

- **Project Name**: twilio-chat-js-cordova-example
- **Description**: Cordova app example for Twilio Programmable Chat with working iOS and Android push messages
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-10-22
- **Last Updated**: 2025-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# twilio-chat-js-cordova-example
This repository contains an example Cordova app with Twilio Programmable Chat client usage.
App is running on both iOS and Android (full functionality with FCM and APN pushes including).

## Chat functionality
Twilio Programmable Chat functionality achieved using [cordova-plugin-twilio-chat](https://www.npmjs.com/package/cordova-plugin-twilio-chat) plugin. Additionally in this project there is [chat-client-helper.js](www/js/chat-client-helper.js), which subscribes to all events which Chat library emits, logs it in console and shows on screen once user is logged in.

## Pushes
You will have to create the FCM and APN credentials and certificates by yourself and pass it respectively in iOS and Android projects (through xcode in the iOS project and through `google-services.json` for Android).

You will need to create credentials in the [Twilio Console](https://www.twilio.com/console/chat/credentials) with created certificates and app identifiers and store it in `configuration.json` file. 

For getting push registration id on the iOS/Android device this example uses [phonegap-plugin-push](https://github.com/phonegap/phonegap-plugin-push). Due to this plugin nature it wraps push message to it's own interface and to be able to process the received push in the Chat lib, in this example we are re-building raw notification from PhoneGap's push in the [phonegap-push-reparser.js](www/js/phonegap-push-reparser.js).   

Keep in mind, that to send pushes you have to turn on the push features for your service instance via [Twilio Console](https://www.twilio.com/console/chat) 

## Token provider
Token is provided by locally running [express.js app](app.js). The app uses ngrok to expose the token provider to the internet - be careful with exposing your actual credentials and secrets to the internet.

Configuration for token provider is stored in the `configuration.json` file. The example with correct structure can be learned from [configuration.example.json](configuration.example.json):
* `tokenGenerator` contains keys needed for token composition (`accountSid`, `signingKeySid`, `signingKeySecret` and `serviceSid` keys) and Credential SIDs for APN and FCM you've created earlier (`fcm` and `apn` keys). 
* `ngrokSubdomain` is optional field if you want to start ngrok with predefined subdomain for token generation
```
{
  "tokenGenerator": {
    "accountSid": "ACxxx",
    "signingKeySid": "SKxxx",
    "signingKeySecret": "xxx",
    "serviceSid": "ISxxx",
    "fcm": "CRxxx",
    "apn": "CRxxx"
  },
  "ngrokSubdomain": "somengroksubdomain"
}
```

Token provider runs on port `3002` on `localhost` and is exposed to the internet with `ngrok` help.

Token provider has multiple exposed endpoints:
 * http://localhost:3002/token (and `https://<yourngroksubdomain>.ngrok.io/token`) token generator GET endpoint, takes in query parameters `identity` and `pushChannel` (`fcm` or `apns`)
 * http://localhost:3002/configuration (and `https://<yourngroksubdomain>.ngrok.io/configuration`) exposes full `configuration.json` for debugging the app

Additionally, ngrok exposes it's own status and inspect endpoint at http://localhost:4040

## Creating your own sample Cordova application with Twilio Chat

### Create new project  
Create new Cordova project with help of cli: `cordova create <project-path> <id> <display-name>`.
 
This repository project was made with this command: `cordova create twilio-chat-js-cordova-example com.twilio.rtd.chat.js.cordova TwilioChatJsCordova`

### Add necessary Cordova plugins to the project:
```
cordova plugin add cordova-plugin-twilio-chat --save
cordova plugin add phonegap-plugin-push --save
cordova plugin add cordova-plugin-whitelist --save
```  
        
### Local Token Provider setup
1. install required node.js modules: `npm install --save-dev body-parser cors express ngrok twilio`
2. create `configuration.json` file in the root folder of the project and fill it with your data (here is the sample [configuration.example.json](configuration.example.json))
3. copy files from this repository: `app.js` and `token-provider.js` to your project root
4. add following section to your project's `package.json`: 
``` 
"scripts": {
    "tokenProvider": "node app.js"
},
```   

### Add Cordova project files to your project
recursively copy `www` folder from this repository to your project

### Android setup 
1. add Android platform to your project: `cordova platform add android`
2. get your `google-services.json` from Firebase Console and put to the root of project
3. add `<resource-file src="google-services.json" target="google-services.json" />` to the `config.xml` inside `<platform name="android">...</platform>` section.
4. try to build your Android project with `cordova build android`

### iOS setup 
1. add iOS platform to your project: `cordova platform add ios`
2. do the `pod install` inside `platform/ios/` folder 
3. open `<your-project-name>.xcworkspace` file with XCode:
  * add signing profile (we recommend to use automatic signing) to your project
  * enable Push in Capabilities section
4. try to build your iOS project with `cordova build ios`

## Running the app
1. do the `npm install` to install all necessary packages
2. start the Token Provider with `npm run tokenProvider` and remember the ngrok url printed in the console.
3. launch the app on Android (`cordova run android`) or iOS (through XCode or with `cordova run ios`)
4. in the login view of the app enter username and token provider host (the ngrok url you've remembered earlier) and press Login button
5. _for iOS see the TODO section_

## TODO
* PushNotification Cordova plugin blocking main thread on iOS for some reason (exact same issue is described here: https://github.com/phonegap/phonegap-plugin-push/issues/1896) resulting in not getting device registration id (and, hence, non-working pushes in iOS). The workaround is to do double-home-press on the device, so the app would go to background and back - then device token is fetched and all is working as it supposed to.