How to Brand Your Product

Our “How to manage Projects” guide provided an introduction to Mason OS configurations, Projects, and how to deploy them via both the Mason Controller and the Mason CLI.

Here, we’re going to cover how to take your Mason Project to the next level with custom branding in the boot-up sequence. Your custom-branded experience begins the moment your end-user powers on their device!

Getting started

First, you’ll want to make sure you’ve followed the steps below to create your Mason account, a Group, and a Project. You can build Projects via either the Mason CLI or the Mason Controller, depending on your preference and level of technical expertise.

1. Create your Mason account
2. Create a Group
3. Create a Project via the Mason CLI or the Mason Controller
4. [optional][Set up your device](/setup-guide#power-on-and-connect)
5. [optional][Move a device into your Group](/how-to/manage-groups#moving-devices-between-groups)
6. [optional][See our white label example on GitHub](https://github.com/MasonAmerica/white-label-example)

Before you begin to white-label your user experience on Mason OS, you’ll need to gather your branded assets, such as the splash image and boot animation. Once created, you’ll need to register and deploy them via either the Mason CLI or the Mason Controller. Let’s walk through it together.

Create, register, and deploy your splash image with the Mason CLI

1. Create your splash image

A splash image in Android is the static image displayed at the very start of the boot-up experience.

By default, Mason devices will show the Mason logo:

tip

If you’d rather follow along with an example splash image, download our default replacement .png on GitHub.

To create your own splash image, use your preferred image editor (such as Photoshop or Figma) to create a branded .png image.

Splash image specifications:

• .png file format
• Square images scale best across device form factors and resolution sizes
• The maximum image width should match the device’s resolution size (ex: a handheld with 1080x2160 resolution would require a 1080x1080 square splash image.)

2. Register your splash image

In our Set-up Guide, we share how to register your artifacts on step 6 of “Build and deploy your project using the Mason CLI.” Let’s go over the process here for your splash screen.

Since the splash image is just a static image, we need to give it a name. We’ll call our splash image mysplash. Name your splash image using any conventions that work for your process. To register your splash screen, we’ll use the CLI command mason register splash. For the purposes of our example, our command would look like:

mason register splash --file mysplash.png --api-key [MASON_API_KEY]

For more details on registering a splash image to the Mason Platform, see our Mason CLI documentation for the command mason register splash.

3. Create your Project

If you don't have an existing Project, your next step will be to create one. Head to our Mason CLI documentation for the command mason_create_project. For the purposes of our example, we'll use the name white-label-example, but you can name your project anything that makes sense. Our command would look something like:

mason create project --name white-label-example \
--description "Creating an example project for white-labeling a project with Mason" \
--deviceFamily D450 --apiLevel 30 --api-key [MASON_API_KEY]

4. Modify your Mason OS configuration

Now that you’ve registered your splash image with the Mason platform, you can reference it in your Mason OS configuration! To do this, you'll add the following YAML to your configuration:

media:
    splash:
      name: mysplash
      version: latest

The media block in your YAML should be a sibling to the apps and os blocks, as you can see in the example below:

os:
  name: white-label-example
  version: latest

apps:
  - name: com.example.app
    package_name: com.example.app
    version_code: latest

media:
  splash:
    name: mysplash
    version: latest

5. Register and deploy your config

Now that you've created your very own custom splash image and added it to your Mason OS configuration, you're ready to see it live in action!

Register your updated Mason OS config using the following command:

mason register config <path to your config> --api-key [MASON_API_KEY]

This will kick off a build of your Project. The success/failure of your build will be shown in the CLI; this will also be reflected in Controller under the Project Details page.

Create, register, and deploy your boot animation with the Mason CLI

1. Create your boot animation

A boot animation in Android refers to the dynamic animations shown while the device is booting up. Boot animations in Android are served in the form of a .zip file.

tip

If you’d rather follow along with an example boot animation, download our default Mason boot animation on GitHub.

You can also extract this file to examine it. You'll notice a desc.txt file in the zip — this file explains to Android how to play your animation.

Example of a Mason-branded boot animation:

Read Android’s official boot animation documentation for detailed instructions on how to create your own branded boot animation.

Boot animation specifications:

• .zip format
• Square animations scale best across device form factors and resolution sizes
• The boot animation zip includes a manifest where an animation size can be declared, causing it to shrink or expand as needed. Try to keep the animation width as close to the device’s resolution size as possible (ex: a handheld with 1080x2160 resolution would require a 1080x1080 square boot animation.)

caution

Compressing the .zip file can create an extra sub directory (nesting all of your files under a parent directory). When you create the .zip, ensure the desc.txt and each of the parts of the animation are at the root of the zip.

Here’s the command we used to create our example: zip -0 -r -o ../myanimation.zip desc.txt part0/* part1/*

2. Register your boot animation

In our Set-up Guide, we share how to register your artifacts on step 6 of “Build and deploy your project using the Mason CLI.” Let’s go over the process here for your boot animation.

Since the boot animation is just a zip file, we’ll need to give it a name. We’ll call it myanimation. Name your boot animation using whichever naming conventions work best for you.

tip

To see an example of valid formatting, check out our sample boot animation file. For more details, visit the Android Docs.

To register your boot animation, we’ll use the CLI command mason register bootanimation.

For the purposes of our example, our command would look like:

mason register bootanimation --file myanimation.zip --api-key [MASON_API_KEY]

For more details on registering a boot animation to the Mason Platform, see our Mason CLI documentation for the command mason register bootanimation.

3. Modify your Mason OS configuration

Now that you’ve registered your boot animation with the Mason platform, you can reference it in your Mason OS configuration! To do this, you'll add the following YAML to your configuration:

  media:
    bootanimation:
      name: myanimation
      version: latest

The media block in your YAML should be a sibling to the apps and os blocks, as you can see below:

os:
  name: white-label-example
  version: latest

apps:
  - name: com.example.app
    package_name: com.example.app
    version_code: latest

media:
  bootanimation:
    name: myanimation
    version: latest
  splash:
    name: mysplash
    version: latest

4. Register and deploy your config

Now that you've created your very own custom boot animation and added it to your Mason OS configuration, you're ready to see it live in action!

Register your updated Mason OS config using the following command:

mason register config <path to your config> --api-key [MASON_API_KEY]

This will kick off a build of your Project. The success/failure of your build will be shown in the CLI; this will also be reflected in Controller under the Project Details page.

Register and deploy your splash image and boot animation via the Mason Controller

If you are a less-technical user and/or are not using the CLI to deploy changes to your product, the Mason Controller has the same functionality with a streamlined, simple-to-use UI.

To register and deploy your splash image and boot animation via the Mason Controller, follow the steps outlined in our Set-up guide here.

You can also follow our video guide on How to Create and Deploy a Build here (3 minutes):

If you would prefer to upload assets directly in Controller without going through the full build wizard, follow the steps outlined here.

---

Congratulations — you’ve successfully white-labeled your product using the Mason platform! If you have any questions, check out our Knowledge Base or reach out to our friendly team at support@bymason.com.