Overview

Here, you’ll find a tutorial to start an Android project with Beagle.

Starting an Android project

For this practical example, we’ll use Android Studio IDE. In case you still don’t have it installed, just access on official Android website and follow the instructions.

After you installed the program, follow the steps below:

Step 1: Open Android Studio and click on Start a new Android Studio project.

Step 2: Choose the Empty Activity option and click on next.

Step 3️: On this page, there are some important information:

  • Inform your project’s name. On this example, we’ll call BeagleApp.
  • Choose which language you’ll use. For Beagle, you should go with Kotlin.
  • Choose SDK minimum 19, because a lower SDK won’t be compatible.
  • Define a package and a Save location according to your preference.
  • Click on Next.

Step 4️: After you made the previous configurations, Android will take some time to build the project because it will be synchronizing all the initials dependencies to initialize the project

Once the initialization is done, you will see this page:

Configuring Beagle

Step 1: Define the dependencies

To start, you have to configure Beagle’s dependencies on your repository. This can be done using the configurations below and downloading Beagle’s library.

  • Open your project on Android Studio.
  • Search for Graddle scripts file on the project.
  • On this file, there are two files gradle name. Open the first one named.build.graddle(project:Beagle).
  • Search for allprojects code block and configure Maven credentials as you see in the list below:
// Add it in your root build.gradle at the end of repositories:
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}
  • Close build.graddle(project:Beagle) file.

Once you made it, we should include kapt plugin and Beagle as dependencies on dependency manager. To do so, follow these instructions:

  • Open thebuild.graddle(Module:app) file

Notice that some plugins are already listed on the beginning of the file as shown below:

  • Then, add the line_apply plugin: 'kotlin-kapt'_

After that, you need to add some dependencies:

  • Search for this file that is moving in dependencies { }code block.
  • Add a ext.beagle_version variable on the top (in this case, out of) the dependencies scope
    • The current release version of Beagle is:Maven Central

Copy and paste the lines below inside your dependencies:

  • implementation “br.com.zup.beagle:android:$beagle_version”
  • kapt “br.com.zup.beagle:android-processor:$beagle_version”
// Add in your app level dependency
ext.beagle_version = "${beagle_version}"
 
dependencies {
    implementation "br.com.zup.beagle:android:$beagle_version"
    kapt "br.com.zup.beagle:android-processor:$beagle_version"
}

At the end of these configurations, your file must be like this:

Step 2: Configure the Android Manifest file

The next step is to update your Android Manifest project by adding a few lines to the file:

  1. INTERNET’s permission so your application can be able to access internet. <uses-permission android:name="android.permission.INTERNET" />
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.beagleexamples">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        ...
        android:usesCleartextTraffic="true"
        ...

Let this file open because we’ll use it again in another moment.

Step 3: Configure Network, Cache and Logger

Now that your project is created, you must configure Beagle settings. To do this, follow the steps below:

Step 4: Create an AppBeagleConfig

For the next steps, you should create an AppBeagleConfig class, that is part of Beagle’s installation and it’s responsible to register some important configurations.

When you create the call, we should guarantee that it’s configured in this way:

  • Noted with @BeagleComponent
  • And extending BeagleConfigclass.

To create AppBeagleConfig, follow these steps:

  1. First, you create a package with all configurations' files.
  2. Then, click with the right button on the main package of your project and click on new > package __like in the image below:

Even though you can name the file as you want to, we’ll recommend for this tutorial that you use the namebeagle.

3. Click with the right button on beagle's package and click on **new&gt;Kotlin File/Class**

__4. __Name it as AppBeagleConfig and then press ENTER

  1. Copy and paste the configurations below on AppBeagleConfig file you just created. Notice that it will implement two attributes: baseUrl and environment.
  • The baseUrl returns the basis URL of your environment.
  • The environment returns the current build state of your application.
  • isLoggingEnabled returns the application’s log view
  • The cache manager configuration.
import br.com.zup.beagle.android.annotation.BeagleComponent
import br.com.zup.beagle.android.setup.BeagleConfig
import br.com.zup.beagle.android.setup.Cache
import br.com.zup.beagle.android.setup.Environment

@BeagleComponent
class AppBeagleConfig : BeagleConfig {
    override val baseUrl: String get() = "http://10.0.2.2:8080" // return the base url based on your environment
    override val environment: Environment get() = Environment.DEBUG // return the current build state of your app
    override val isLoggingEnabled: Boolean = true
    override val cache: Cache get() = Cache(
        enabled = true, // If true, we will cache data on disk and memory.
        maxAge = 300, // Time in seconds that memory cache will live.
        memoryMaximumCapacity = 15 // Memory LRU cache size. It represents number of screens that will be in memory.
    ) // Cache management configuration
}

Step 5: BeagleActivity

Beagle offers a default Activity to manage all server-driven activities. However, it is possible to create a more specific activity to handle server-driven screens differently. You will create a new activity inherited from BeagleActivity and it will annotate with @BeagleComponent. Check more information on how to create one at the Beagle Activity page.

Step 6: Initialize Beagle and Design System

Now , you must initialize your Application so Beagle can manage the other configuration’s files. To do so, just click onMake project (HAMMER symbol) or use the command CTRL + F9.

When it’s initialized, Beagle will automatically create a BeagleSetup file that will be in the folder with the generated files, like in the image below:

Step 7: Create an AppApplication class

On this step, you need to create aKOTLIN class that extends to the Applicationclass. For this example, we’ll name it asAppApplication.

It’s necessary to make some configurations on this folder so it can BeagleSetup().init(this) function on your onCreate method. Follow these steps:

  1. Click with the right button on your project’s main package (beagleapp) and choose:
    • new > Kotlin file/class
    • Name the file as AppApplication and press enter
    • Configure the file as in the example below:
class AppApplication: Application() {

    override fun onCreate() {
        super.onCreate()
        BeagleSetup().init(this)
    }
}
  1. To finish this configuration, you must state the class on the AndroidManifest we created in the beginning.

The name of yourapplication now it’s the same of the class you created. Update the Android Manifest as it’s indicated below:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.beagleexamples">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
        android:name=".AppApplication"
        
        ...

All you have to do now is set up a backend to answer your application’s requests. Once you made this configuration, start your application and you’ll see your first server-driven screen!

Step 8: Display your Server-Driven Screen

It’s very simple to show a server-driven screen. Now that all Beagle’s configuration is done, you just have to follow these steps:

  • Open the file MainActivity.kt
  • State the intent as listed below. It will define the address of screen’s information on the backend you configured.
  • Copy and paste the intent listed below on onCreate method.
val intent = this.newServerDrivenIntent<AppBeagleActivity>(ScreenRequest("/screen"))
startActivity(intent)
finish()
  • YourMainActivity.kt must be like this:

Now you just have to click on Run app and check out your emulator’s screen!
You will see this screen:


Design System with Beagle Android

Here, you’ll find a tutorial to configure a Design System with Beagle for Android.


Last modified June 2, 2021: adjust tutorial android (#600) (ef14f808)