Creating Apps From Scratch

If you decide not to use the Wizard, you can still create a new Android Studio project and then build an app using the SDK libraries, or add the SDK to an existing project. To do this, you'll need to modify the top-level and module-level build.gradle files manually to include all required repositories, dependencies, and settings.

The top-level file stores configuration options common to all sub-projects/modules. The module-level file stores options for your new app.

To generate proxy class Java files, use either the OData Gradle Plugin or the Proxy Generator CLI tool. Both tools are included in the software package.

To use the OData Gradle Plugin, modify the two build.gradle files to add the plugin as a dependency and configure it as required. To use the Proxy Generator CLI tool, open a command prompt and enter the required command. See Using the OData Proxy Class Generator Command-line Tool for more information.

Prerequisites

You have run the installation script to install the SDK. See Installing the SAP Cloud Platform SDK for Android for more information.

Procedure

1. From the Android Studio Welcome screen, select Start a new Android Studio project and complete the Create New Project wizard. Refer to your Android Studio documentation for further information.

2. From the project tool window, navigate to the appropriate folder and open the build.gradle file in the editor window.

   For the top-level file, go to <yourproject> -> gradle. For the module-level app, go to <yourproject> -> app.

3. Add the required dependencies to the project

4. Generate OData proxy classes. See Using the Gradle Tool to Generate Proxy Classes for more information.
5. To ensure you can debug your new project, enable trace logging for your project; see Debugging.

Adding Required Repositories to Your Project

Add all required repositories including the local Maven repository to your project by modifying the app module build.gradle file for your project.

From Android Studio, open the top-level build.gradle file and add the following to all the repositories blocks:

buildscript {
    repositories {
        google()
        jcenter()
        mavenLocal()
    }
}
allprojects {
    repositories {
        google()
        jcenter()
        mavenLocal()
    }
}

Alternatively, we offer a better similar way to well-known public repositories such as Maven Central, Bintray and JCenter: The SAP Cloud Shipment channel. In this very specific case of the Android SDK, we are talking about a customer-facing Maven repository that you can configure in your projects to consume the Cloud Platform SDK for Android without any additional manual downloads. We finally publish Android SDK libraries via SAP-hosted Maven infrastructure in the DMZ. The process to use this is:

• Obtain a technical user from the SAP Repositories Management site, and download the Basic Auth Password file. See Creating Required Credentials for further details.
• Set the user credentials in ENV (SAP_MAVEN_USER, SAP_MAVEN_PASSWORD)
• Create a $HOME/.gradle/init.gradle script with the following contents:

allprojects {
     ext.SAPRepoConfig = {
         maven {
             url "https://73555000100800001281.maven.repositories.sapcdn.io"
             credentials {
                 username "$System.env.SAP_MAVEN_USER"
                 password "$System.env.SAP_MAVEN_PASSWORD"
             }
         }
     }
     buildscript.repositories SAPRepoConfig
     repositories SAPRepoConfig
 }

Now all Android projects will also fetch dependencies from SAP infrastructure.

Note

You can add the above Maven project to your project repositories in the app module build.gradle file, the above settings can be maintained on the project level.

Adding Project Dependencies

Add one or more of the SDK for Android components as required for your mobile application. The SDK includes the following libraries:

Library	Gradle Dependency Line
Fiori	com.sap.cloud.android:fiori:3.0.0
Foundation	com.sap.cloud.android:foundation:3.0.0
OData	com.sap.cloud.android:odata:3.0.0
Offline OData	com.sap.cloud.android:offline-odata:3.0.0
Onboarding	com.sap.cloud.android:onboarding:3.0.0
OnboardingFlows WelcomeScreen	com.sap.cloud.android:onboardingflows-welcomescreen:3.0.0
OnboardingFlows Basic Authentication	com.sap.cloud.android:onboardingflows-basicauth:3.0.0
OnboardingFlows OAuth	com.sap.cloud.android:onboardingflows-oauth:3.0.0
OnboardingFlows SAML	com.sap.cloud.android:onboardingflows-saml:3.0.0
OnboardingFlows OTP	com.sap.cloud.android:onboardingflows-otp:3.0.0
OnboardingFlows StoreManager	com.sap.cloud.android:onboardingflows-storemanager:3.0.0
OnboardingFlows Logging	com.sap.cloud.android:onboardingflows-logging:3.0.0
OnboardingFlows EULA	com.sap.cloud.android:onboardingflows-eula:3.0.0
Google Vision	com.sap.cloud.android:google-vision:3.0.0

Add the following SDK libraries as dependencies to your module-level build.gradle file:

dependencies {
    def versions =  [sapCloudAndroidSdk: '3.0.0']

    implementation "com.sap.cloud.android:fiori:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:foundation:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:odata:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:offline-odata:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboarding:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-welcomescreen:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-basicauth:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-oauth:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-saml:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-otp:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-storemanager:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-logging:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:onboardingflows-eula:$versions.sapCloudAndroidSdk"
    implementation "com.sap.cloud.android:google-vision:$versions.sapCloudAndroidSdk"
}

If you intend to enable logging, include logback-android dependencies to this enclosure:

dependencies {
    ...
    implementation 'com.github.tony19:logback-android:2.0.0'
}

Using these libraries will require multiDex. To enable this for your project, add the following to the defaultConfig section of your module-level build.gradle file:

android {
    defaultConfig {
        ...
        multiDexEnabled true
    }
    ...
}

Update the target SDK version and compatibility versions as follows to your module-level build.gradle file:

android {
    compileSdkVersion 28
    ...
    compileOptions {
        targetCompatibility 1.8
        sourceCompatibility 1.8
    }
}

Initializing SDK

Since there are many modules in the Foundation component, using them in the client code to integrate your application with SAP Cloud Platform Mobile Services will require lots of boilerplate code in the mobile application. To reduce the boilerplate code from your mobile application, a new API is introduced as below:

public static void start(
        @NonNull Application application,
        @NonNull OkHttpClient httpClient,
        @NonNull SettingsParameters settingsParameter,
        @Nullable Class<? extends MobileService>... services) {
    ...
}

When both settingsParameter and httpClient are ready, this method can be called to initialize all the services, that is, the modules you want to use in your application, for example, Push, Usage, etc.

Note

Since the initialization process will depend on the lifecycle of the mobile application, before invoking the start method, make sure the follow lifecycle callback is registered.

registerActivityLifecycleCallbacks(AppLifecycleCallbackHandler.getInstance());

The parameters are explained below:

1. SettingsParameter

   SettingsParameter mainly contains the following attributes which will be needed in various API calls:

   • BackendURL - The server URL from the mobile services application APIs end points. This is used as the base URL for constructing various REST API end points.
   • ApplicationId - The application Id from the application definition in mobile services

   • DeviceId - The device Id is used to identify the device in the mobile application that is running. It is best to use an Id that is same across application sessions. It is recommended to use ANDROID_ID for this. The Device Id plays a role in push notifications and valuable Admin functionality in mobile services.

     import android.provider.Settings.Secure;
     ...
     String deviceId = Secure.getString(context.getContentResolver(), Secure.ANDROID_ID);
     

   • ApplicationVersion - The application version for your mobile application. This version is used in reporting APIs.

2. OkHttpClient

   This will be used for API calls in your application, and it will be different based on the authentication method you're using.

   Note

   Please use ClientProvider.get() to get HTTP client instance after invoking MobileServices.start since the initializer will add additional interceptor into it.

3. Class<? extends MobileService>... services

   This parameter represents all the services to be initialized in your application. Currently the following services are supported:

   • ClientResourceService to download client resources automatically;
   • LogService to setup the log settings and upload logs automatically;
   • PushService to enable Firebase messaging service in your application;
   • SettingsService to download client policies automatically;
   • UsageService to leverage the auto session, auto upload and other client usage features;
   • UserRoleService to download user role information automatically;

   This parameter only takes the class name as the value, it means most of the services have default values defined inside, for example, the default UsageService will use auto session feature and a default usage store name, if you want to define your own settings, you can do that before calling the start method.

   Please follow the links above to see the details.

---

Last update: September 30, 2020