Extending Survey123, Part 1: White Labeling
9849
11
04-29-2018 04:36 PM
For this blog post, and the subsequent blog post on extending Survey123's functionality, I've created a user story for a fictitious municipality called the City of Cilantro that will help guide the customization process. Also, a public repo with the customized app is available at Github: Cilantro Surveys
I. User Story
The City of Cilantro needs a custom version of Survey123 that will be used by various city departments to conduct public and private surveys. The city currently has three customization needs:
- The app needs to be branded to match the organization. [Not extending core functionality]
- The city needs the ability to print the time and location onto new photos taken with some surveys. [Extending core functionality]
- Some surveys used in the field will include the scanning of barcodes as the only action required of the survey. The application will need to automatically submit the survey after the barcode is successfully scanned and then open a new survey immediately upon successfully submitting the previous survey. [Extending core functionality]
This blog post will address the first customization need. Updating the user interface (UI) to match an organization's branding doesn't affect or amend the application's core functionality and requires no coding experience (there is one caveat to this currently which is noted in section III.4). Let's first look at the asset's needed to create the custom look and feel before downloading the template.
II. Assets & Information Needed
a. App Name
Cilantro Surveys
The app should have a distinct name. It should not be called Survey123. For the City of Cilantro, 'Cilantro Surveys' was chosen as it referenced the city's name and also kept the name simple and succinct.
b. Branding Color
#543e36
The Survey123 application has one main color used throughout the UI that 'brands' the look and feel. Survey123's branding is built around a hue of green, and can be seen throughout the UI of the application as well as the website and associated marketing materials. When customizing Survey123, it is highly recommended that a different color be used in order to help distinguish the app from Esri's production version of Survey123. The color should ideally match the branding guidelines and needs of the organization that is customizing the app. The City of Cilantro uses a brown hue in their logo, so that same hue of #543e36 will be used in the custom app.
c. App Icon
The app icon is what the user will see in the device's user interface and will be touched or clicked to open the app.
- 512 × 512 (pixels)
- .png file
d. Launch Screen Image Overlay
The launch screen overlay is a graphic that will appear above a colored background when the app is launched into the device's memory.
- 768 × 768 (pixels)
- .png file
- Should include transparency or the background color should match the color set for the background color in the app's settings. In this example the image includes white graphics on a transparent background. The background color is set to #543e36 in app's settings.
e. App Thumbnail [for ArcGIS only]
The app thumbnail is used to help distinguish the app in ArcGIS galleries. It is used throughout the web and AppStudio to visually reference the application item.
- 200 × 133 (pixels)
- .jpg or .png file
f. Company / Organization Logo [optional]
The company / organization logo is an optional asset. If included, it will appear on the app's About view. It can additionally be set to open a custom url to an external website.
- Height should be a maximum of 200px. The width will be automatically adjusted to preserve the image's aspect ratio and fit the logo into horizontal space on the About view.
- .png or .jpg file
g. Custom Font [optional]
The Survey123 template allows for the use of a TrueType font family in the customized application.
- .ttf (TrueType) files supported.
- Ensure that the font is licensed or has a license that allows it to be distributed with the app.
- For the Cilantro Surveys app, we are using the Raleway font family available from Google Fonts, which has an Open Font License.
III. Steps to UI Customization
Now that I've outlined the assets and information needed to create a custom version of Survey123, the next step is to download the template and get started. I'll go through this step by step and reference the assets and information listed above along the way.
1. Download the template
- Open AppStudio for ArcGIS. You don't have to log into your ArcGIS organizational account in order to download the template, but it is a best practice.
- Click "New App"
- Click the "Enterprise" tab in the New App dialog
- Select Survey123 (Template), enter the title of the app ("Cilantro Surveys" in this example) and click "Create"
- The new app template will download and appear in the AppStudio gallery.
2. [Optional] Create the fonts folder and add the font files
This step is only required if you are using a custom font family.
- Right-click the gallery card for the app in AppStudio and select Open in folder.
- Open the "Controls" folder
- If the folder doesn't contain a "fonts" folder, create one.
- Copy all of your .ttf files into that folder.
- In this example we'll be copying the Raleway fonts to the folder.
3. Update the app's settings and assets
Now comes the most significant step where the assets and settings for the app are updated.
- Make sure the gallery item for the downloaded template is selected and then open Settings for the app. This can be down by right-clicking on the gallery item and clicking Settings from the menu, or using the side menu.
- Details Tab
- First update the app's details under the Details tab.
- Click the thumbnail and replace it with the app thumbnail created for the app (See section II.e)
- Update the app's summary, description and access use and constraints to reflect the new app. The description will appear in the app's About view.
- Survey123 Tab
- General Tab
- Text color: The text color used in all non-title text in the app. I'll leave this set to the default value of #4c4c4c.
- Background color: This will set the background color displayed in the gallery and the survey info views. I'll leave this set to the default of #efeeef.
- Title bar text color: This sets the foreground (text) and icon colors for the top bar in the gallery and survey info views. I'll leave this set to the default of #ffffff. Because the branding and background color for Cilantro Surveys is dark, the white text will contrast well against it.
- Title bar background color: The background color used in the app's title bars.
- For Cilantro Surveys I am using the branding color of #543e36 (see section II.b).
- Font Family: This is where the name of the custom font is entered. For Cilantro Surveys I am using the Raleway font family.
- Note: The text entered here would be the same text entered for the css font-family property if the font were being used on the web (e.g. font-family: 'Raleway';)
- Other Properties
- backgroundTextureImage: This property is no longer used.
- companyLogo: The company logo that appears on the app's About page (see section II.f).
- companyUrl: URL opened via the company logo on the About page.
- formBackgroundColor: The default background color used for forms in the app.
- startBackgroundColor: The background color of the opening splash screen.
- For Cilantro Surveys I am using the branding color of #543e36 (see section II.b).
- startForegroundColor: The foreground color of the opening splash screen.
- startOverlayImage: The image that appears on the opening splash screen.
- For Cilantro Surveys I'll set this to our company logo as well (see setion II.f).
- General Tab
- Resources Tab
- App Icon
- I'll set this to the icon created with the assets (see section II.c)
- Launch Image
- Overlay image: I'll set this to the launch image created with the assets (see section II.d).
- Background Image: I won't use this property with the customized app.
- Background color: I am using the branding color of #543e36 (see section II.b).
- App Icon
4. Fix small bug in code [only for templates based on version 2.7 or less]
Survey123 templates based on version 2.7 of the app or less have a small bug in the code that needs to be fixed in order for the branding color to be reflected on the survey view. To fix the bug do the following:
- Open the app codebase in Qt Creator. This can be done by right-clicking on the app card in AppStudio and selecting "Edit in Qt Creator" or by highlighting the app in the AppStudio gallery and clicking the "Edit" button in the side panel.
- Open the following file by using the file browser in the left panel of Qt Creator: template > SurveyView.qml
- Within the style property of the XForm component in SurveyView (approximately line 501), add the following 2 properties below the line: fontFamily:app.fontFamily
titleBackgroundColor: app.titleBarBackgroundColor
titleTextColor: app.titleBarTextColor
- You can view the code in the Cilantro Survey's public repo at CilantroSurveys/SurveyView.qml
- Save the file and close Qt Creator.
5. Upload the app
Upload the app to ArcGIS online. This will allow you to register a client id for the app so that it can use OAuth for login authentication, as well as provide access to CloudMake.
6. Register the client id in order to use OAuth
In order for users to be able to log in to your app with their ArcGIS Online or Portal credentials, a client id must be registered for the app. If the app is located on ArcGIS Online, registering the client id is an easy process*.
- Open Settings for the app (see Step 3.1 above).
- Click the Advanced button on the bottom bar next to Apply.
- Under ArcGIS Client ID click the "Register" button (You must be logged in to ArcGIS Online).
- Settings will register the app with ArcGIS and return a client id that will appear in the text field.
- Once the client id is returned and visible, click "Apply".
- That's all
*Note: If the app needs to authenticate to a Portal for ArcGIS, you will need to follow instructions similar to those outlined in this article (substitute your app's name for Survey123 in the article).
7. Test and Build app
Now the only thing left to do is build the app. Before doing that, most of the changes made in the previous steps can be previewed in AppRun or AppStudio Player.
- To open the app in AppRun either double-click the app card in the AppStudio gallery or click "Run" in the AppStudio side panel.
- For more information on AppStudio Player, see: Guided tour—AppStudio for ArcGIS | ArcGIS
Building the app via CloudMake or Local Make is beyond the scope of this blog post. However, please note that in order to build the app for various platforms appropriate developer certificates and provisioning profiles are required.
That's all there is for white label branding Survey123. However, if you want to finesse the app's look and feel even further, feel free to jump into the code .
11 Comments