Whitelabeling mobile apps

In this guide we will cover how to rebrand Rocket.Chat Mobile Apps to suit your styling.

Here we will show you how to customize:

  • The App Icons

  • Splash Screens

  • App Name

  • Colors

Important

  • This document is updated after every release, so we can guarantee it's stable for production

    • develop branch might be different from this

  • Keep in mind that you will need an intermediate knowledge of Android/iOS development and basic Javascript knowledge

  • Our repo contains targets/build flavors to build both our Experimental and Official apps

    • Both apps are equal, but released at different pace on the stores

    • If you see an Experimental folder, don't be scared of breaking anything. It's just a folder containing the assets for the non-official app

Repo

General

Firebase

Creating a new project on Google Cloud Platform

  • By the text Google Cloud Platform there is a dropdown, open and then “Create project”

  • In the dialog give an project name then “Create”

  • Wait the creating process, you can follow in notifications by your avatar

  • You will be redirected to the project page after creation

Creating new Firebase project

  • Click on “Add Project”

  • Enter the project name you created on previous step

  • Follow the wizard until Firebase project is created

  • We’re going to create the apps later on the tutorial

iOS

General setup

  • Open RocketChatRN.xcworkspace on Xcode (11.7 or newer)

  • On General tab, select “RocketChatRN” and change Display Name, Bundle Identifier, Version and Build

    • Note: as explained on Important section, we have two targets and we're going to cover the default one on this doc, which is the Experimental app.

  • Select “ShareRocketChatRN” and change the same properties

    • Display Name and Bundle Identifier are different from the previous target

    • Version and Build must be the same on all targets

  • Select “NotificationService” and change the same properties

    • Display Name and Bundle Identifier are different from the previous target

    • Version and Build must be the same on all targets

  • On Signing and Capabilities, check “Automatically manage signing”, select your app group and add a keychain group

  • Select “ShareRocketChatRN”, check “Automatically manage signing”, select your app group and add the same keychain group

  • Select “NotificationService”, check “Automatically manage signing”, select your app group and add the same keychain group

  • Set the same app group on RocketChatRN/Info.plist, ShareRocketChatRN/Info.plist and NotificationService/Info.plist

  • Set the same keychain group on RocketChatRN/Info.plist, ShareRocketChatRN/Info.plist and NotificationService/Info.plist

  • It needs to be the same on all entitlements

  • Change the app icon on Experimental.xcassets/App Icon

  • Change the app splash screen on Experimental.xcassets/Launch Screen Icon

  • Change the splash background colors on Experimental.xcassets/splashBackgroundColor

  • Set your Bugsnag API key on RocketChatRN/Info.plist

Generating iOS app on Firebase

  • On “General” tab, click on “iOS” button under “Your apps” section

  • Enter your bundle ID and then “Register app”

  • Download config file and move it as instructed

  • Add it to all targets

Running the app

  • Execute the following on project terminal

    • yarn

    • npx pod-install

    • yarn ios

Android

General setup

  • Similarly to iOS, we have build flavours to generate our Official, Experimental and F-Droid versions of the app

    • experimental and official folders contain app icons and splash screens

    • play and foss folders contain necessary code to run the app with or without Google Play services, respectively

      • foss build doesn't contain push notifications implemented

    • main folder contains core implementations

    • debug folder contains code to run the app in debug mode

    • This doc is going to focus on building the Experimental app, so we're going to use experimental, play debug, and main folders

  • Set APPLICATION_ID, VERSIONCODE and BugsnagAPIKey on ./android/gradle.properties

  • Generate a new image asset for ic_notification and target main

  • Generate a new image asset for ic_launcher and target experimental

  • Change splash screen background and notification text color on ./android/app/src/experimental/res/values/colors.xml

  • Change splash screen logo on ./android/app/src/experimental/res/drawable-xxhdpi/splash.png

  • Change app name and share extension name on ./android/app/src/main/res/values/strings.xml

Generate upload key

  • This step will generate the keystore that is going to verify your app on Google Play

  • Execute the following on terminal

    • cd android/app

    • keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

  • Credentials will be prompted

  • Set KEYSTORE_PASSWORD and KEY_PASSWORD on ./android/gradle.properties with the passwords you were prompted

Generating Android app on Firebase

  • On “General” tab, click on “Add app” button under “Your apps” section and then “Android”

  • Enter your bundle ID and then “Register app”

  • Download config file and move it as instructed

Running the app

  • Execute the following on project terminal

    • yarn

    • yarn android-whitelabel <YOURAPPID>

    • For example, the app created on this document would use yarn android-whitelabel chat.rocket.whitelabel

  • Note: this script uses experimentalPlayDebug build flavor. When you build your app on release mode, use experimentalPlayRelease

Push notification

Configuring gateway

  • Go to your Rocket.Chat admin page > Push

  • Disable “Gateway” and press “Save changes”

  • Also disable “Production”, if you’re trying in debug mode

  • Expand “Credentials and Keys” section

Configuring Android

  • Go to Cloud Messaging on Firebase settings

  • Copy “Server Key” token from Firebase into “GCM API Key”

  • Copy “Sender ID” into “GCM Project Number”

Configuring iOS

  • Make sure you’ve done “Creating Push Notifications certificates” first

  • In your terminal, go to the folder which contains your push files (CSR, .cer, .p12).

Generating PEM files (Development)

  • Execute

    • openssl x509 -in aps_development.cer -inform der -out DevPushCert.pem

    • openssl pkcs12 -nocerts -out DevPushKey.pem -in yourP12File.p12

  • You must set a password for your PEM file

Generating PEM files (Production)

  • Execute

    • openssl x509 -in aps.cer -inform der -out PushCert.pem

    • openssl pkcs12 -nocerts -out PushKey.pem -in yourP12File.p12

  • You must set a password for your PEM file

Copying PEM files to Rocket.Chat

  • Copy the contents of your development PEM files and password into APN Dev Key, APN Dev Cert and APN Dev Passphrase

  • Copy the contents of your production PEM files and password into APN Key, APN Cert and APN Passphrase

  • You can use cat on terminal to get the content of your PEM files

    • cat PushKey.pem

  • Save and restart your server

  • Log into the server as the same user on your mobile device and close it (it won’t receive push notification, if it’s open)

  • Open Push settings on admin from desktop and click “Send a test push to my user”

Developer Apple

Login to Apple Developer

Creating an App Identifier

  • Add description and Bundle ID

  • On Capabilities, select App Groups and Push notifications

  • Click “Continue” and then “Register”

Creating an App Identifier for our Share Extension

  • Add description and Bundle ID

  • This time, select only App Groups under Capabilities

  • Click “Continue” and then “Register”

Create an App Identifier for our Notification Service

Creating an App Group

  • Enter a description and an Identifier

  • Click “Continue” and then “Register”

Applying App Group

  • Click on the first identifier you created

  • On “App Groups”, click “Configure”

  • Select the App Group you created and click “Continue”

  • Click “Save”

  • Repeat these steps for the second identifier you created for the Share Extension and NotificationService

Creating Push Notifications certificates

Development SSL Certificate

  • Download the certificate and install it on your machine (follow instructions on the screen)

  • After installing it, “Keychain Access” should have opened automatically on your Mac

  • Export the certificate to generate a .p12 file

  • For simplicity, save it in the same folder of your CSR and .cer. You’ll need it later.

Production SSL Certificate

  • Download the certificate and install it on your machine (follow instructions on the screen)

  • After installing it, “Keychain Access” should have opened automatically on your Mac

  • Export the certificate to generate a .p12 file

  • For simplicity, save it in the same folder of your CSR and .cer. You’ll need it later.