Repository navigation
Using Android Studio to update the project for your organization
We will be using Android Studio to run the OrgTrac application and to run your organization's application once we have updated all the appropriate configuration files. We will need to update a few things in order to convert the OrgTrac application into you own. The required updates we will need to do include updating the package name, application name, and Contentful keys. Optionally we can also update the application colors, error messaging, and application icon.
Before we get started we will first need to open Android Studio and configure it to run the OrgTrac application. Once we've done that and verified that we can run the OrgTrac application we will walk through the updates to make the project into our organization's application.
We will start with opening Android Studio and configuring it to work properly with our project. Launch Android Studio from the location it was installed in. You will be prompted to complete installation. Simply choose the option that applies to you, likely Do not import settings and click OK.
From here Android Studio will begin the Setup Wizard Process, let's walk through it.
On the Welcome screen we will simply click Next.
On the Install Type screen we will choose just choose the Standard installation and click Next.
On the Select UI Theme screen simply pick the theme you like most, I prefer the Darcula, and click Next.
On the Verify Settings screen simply click Finish, it should look similar to this.
Clicking Finish on the Verify Settings will begin to download all the libraries and components needed by Android Studio. When the process begins you'll see the Downloading Components screen, once this process finishes you will simply click Finish to continue.
Now you are ready to use Android Studio and will be prompted with the Welcome to Android Studio screen. Here you will select the Open an existing Android Studio project option, navigate to the folder you downloaded the project to using GitHub Desktop.
Now you will land on the Project Screen in Android Studio, this will actually be the main screen you will use while within Android Studio. However, for the time being we still need to update the project in order to use Android Studio to Run and Update OrgTrac. We'll do this by clicking the Install Build Tools 28.0.2 and sync project text to initiate installing the needed build tools. The portion with 28.0.2 may change when OrgTrac is updated so don't worry if this version number does not match what you see. Additionally, you can hide the What's New panel by clicking the hide panel button.
When prompted with the License Agreement Screen you will need to click the android-sdk-license, Accept, then Next to accept the agreement and continue.
Once the Component Installer completes you'll be able to click Finish to continue.
You may be prompted with the Android Gradle Plugin Update Recommended dialog, if so you'll want to update to the latest, just click Update and Android Studio will make the appropriate adjustments.
Now that we have Android Studio completely setup we'll be able to launch the OrgTrac application. We'll start by clicking Run selected configuration button in Android Studio.
This will launch the Select Deployment Target dialog. This is where we will be able to choose an Emulator to run the application on. But first we will need to configure an Emulator to use. In order to start the process of creating an emulator click Create New Virtual Device.
On the Select Hardware screen we will choose the emulator configuration we want to use. Since I am a fan of Google and the Phones they produce we will create an emulator for a Google Pixel 2 XL phone then click Next.
On the System Image screen we will need to select the Pie option to download the system image allowing us to launch the emulator.
This will start another License Agreement screen, we'll select the license, Accept, then Next to accept the agreement and continue.
Once the Component Installer completes you'll be able to click Finish to continue and go back to the System Image screen.
Now that we are back on the System Image screen with the Pie image selected we will be able to select Next and continue setting up the emulator.
The last part of setting up the emulator is on the Android Virtual Device (AVD) screen. The default settings on this screen are fine so just click Finish.
Once we've completed this we'll be taken back to the Select Deployment Target where we will now be able to select Pixel XL 2 API 28 and click OK.
This will cause the launch of the emulator. Once the emulator is fully loaded the OrgTrac application will be installed on it and launched automatically.
Awesome!! Now you are ready to update OrgTrac for your own organization!
Now we are ready to make OrgTrac our own! We'll need to change several files in order to do this so we will start by opening all these files in Android Studio. The files we will be opening are build.gradle (Module: app), strings.xml, contentful.xml, and colors.xml. Just double click each to open them in new tabs in Android Studio.
The first file we will need to change is the build.gradle (Module: app) file. We need to change applicationId, this is the unique package name that the Google Play Store will use to distinguish the organization’s application from all the other applications in the store. This value must be changed and must be unique. Typically it's a reverse url, for example if OrgTrac had a website url hosted on CSUN it might be 'orgtrac.csun.edu' so the applicationId would be 'edu.csun.orgtrac' as it is for the OrgTrac application. This value and what it should be is more or less arbitrary, simply needing to be unique, but by convention follows this example.
Once you update the an action bar with Sync Now will appear. You need to click this to cause Android Studio to update the project accordingly for you organization's application. This process can take a little time so be patience and wait for Android Studio to complete the Sync process before continuing.
The next file we will need to change is the string.xml file. We need to change app_name, this is the name that the user will see under the icon once the application is installed. This is normally a short name consisting of 10 or less characters. The value for app_name can be as long as you want but should be kept short so the user can see it, if it's too long it will be cut off in the application tray.
The last file we will need to change is the contentful.xml file. We need to change cf_cda_token and cf_space_id, these are the values that the application uses to synchronize the data from the Contentful API with the application.
In order to get these files we will need to go back to Contentful and click API keys under Settings.
On the APIs screen under the Content delivery / preview tokens tab click Example Key 1
We will use the values on the Example Key 1 screen to update the corresponding values in the contentful.xml file in Android Studio.
Now you are done. Believe it or not OrgTrac is now completely your own. If you want to make the optional changes just continue to the next step Make Optional Changes for Our Organization. If you really just want to see your organizations application work head to the Run Your Organization's Application in Android Studio!! section below.
Updating your application colors is pretty straight forward but the level of customization is currently limited. There are three colors values you can change: colorPrimary, colorPrimaryDark>, and colorAccent. These must be hexidecimal values and are in the colors.xml file. Have fun changing the colors and seeing how the application looks when you run it.
Additionally, you can change the text shown when the application encounters an error. These values are found in the strings.xml file after the app_name value you changed earlier.
These values are shown in the application like the image below. Feel free to update them with you own attitude and style if you wish to do so.
Every application has an application icon. We can create our own using the Configure Image Asset wizard. We will launch it by right clicking res, choosing New then Image Asset.
Once in the Configure Image Asset wizard go about creating your own application icon by modifying the values in the Foreground Layer, Background Layer, and Legacy tabs. Once you like what you see click Next, on the following screen click Finish. When you run your application again from Android Studio using the Select Deployment Target dialog the new version of the application including the new application icon will be installed on the emulator you chose.
Now that you have made all the changes required to make OrgTrac your own, and maybe some of the optional changes as well, we can now launch it! As we did with OrgTrac we will launch our application by clicking Run selected configuration button in Android Studio.
We'll be taken to the Select Deployment Target where we will select Pixel XL 2 API 28 and click OK.
Well look at that! Now you are actually running your application!