Skip to main content
Version: 1.1.0

Quickstart Guide

Exploring the Example App​

The quickest and easiest way to get yourself familiarized with our Mobile SDK for Android and its features is to check out our example app on GitHub. Without having to write any code yourself, you can just clone this project on your local system, go through the integration demos, and run it in an emulator or on a real device. Please refer to the repository’s readme file for further instructions.

Integration into an Existing App​

If you already have an app or are about to start developing one, here are the first steps you need to take to get the ip.labs Mobile SDK up and running.

Prerequisites​

We presume, that you have a few things already in place at this stage:

  • A basic Android app that you want to integrate the SDK into.
  • Your app targets Android 10 at API level 29 or higher.
  • Your app is allowed to request Internet access permission.
  • Your codebase consists of native Kotlin code.
  • Gradle is used for build tooling matters.
  • Development is taking place in the latest Android Studio IDE.

With these formalities out of the way, let’s dive right in!

Adding the Android Library​

The ip.labs Mobile SDK for Android is delivered as a Maven dependency. This way, you can easily integrate it into your Android Studio app project with a simple link and also get notified about updates.

  1. Load your existing app project in Android Studio.

  2. Locate the settings.gradle file and add a new Maven repository with the URL https://s3.eu-central-1.amazonaws.com/mobile-sdk/android/releases. It should look like this afterwards:

    settings.gradle
    dependencyResolutionManagement {
        repositories {
            maven {
                url 'https://s3.eu-central-1.amazonaws.com/mobile-sdk/android/releases'
            }

            // Other repositories like google(), mavenCentral() etc.
        }
    }

    // Other instructions…

  3. Now you can reference the actual library dependency in your app-level build.gradle file:

    build.gradle (:app)
    dependencies {
        implementation 'de.iplabs:mobile-sdk:1.1.0'

        // Other dependencies…
    }

    // Other instructions…

  4. Trigger a Gradle sync by clicking “File” → “Sync Project with Gradle Files” in the IDE’s menu bar to download the library from our Maven repository to your system.

The Mobile SDK is now available in your project and ready to be imported, initialized, and used.

Initializing the SDK​

The SDK provides a central entry point for almost all interaction with its functionalities, that acts like a singleton class, providing various methods at your disposal. It is called IplabsMobileSdk and to start working with the SDK, it must be initialized first through its initialize method along with a fairly small set of configuration parameters. These parameters are:

  • operatorId
    In the ip.labs ecosystem, an operator ID represents your store and the configuration and content data tied to it. The specific set of products you want to offer called a “portfolio” is a good example of such data, that is associated with your dedicated operator ID.

  • locale
    Locale string, identifying your operator’s language, e.g. “en_US”.

  • baseUrl
    Backend endpoint’s URL, used to connect to the ip.labs infrastructure for data exchange.

  • externalCartServiceBaseUrl
    External Cart Service (ECS) backend endpoint URL for the ordering process.

  • localProjectsLocation
    Path to a local directory, in which projects can be stored for later editing / reuse.

On top of that, a few optional parameters exist:

  • translationsSource
    An InputStream, allowing the SDK to access and apply translations for its UI texts for non-English-speaking audiences. This should point to a JSON file containing key-value mappings. See translation docs for details.

  • userTrackingPermission
    Must be one of the values from UserTrackingPermission, either allowing or forbidding collection of user analytics data. Tracking is forbidden by default. See user analytics docs for details.

To just play around with the SDK, you can use the values in the example below as initialization parameters, which refer to a demo instance. As soon as you obtained real values from our customer support, you should switch to those instead to get access to your actual product portfolio and server side integrations.

It is recommended to initialize the SDK early on, right after your app was started. A good place for this could e.g. be the creation phase of your main Activity. Internet connection is not required for the initialization process.

So here is what a basic assembled initialization call looks like with aforementioned sample data:

MainActivity.kt
package com.example.yourapp

import de.iplabs.mobile_sdk.IplabsMobileSdk
import java.net.URL
// Other imports…

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        IplabsMobileSdk.initialize(
            // Use your specific values for the following parameters
            // as soon as you obtained them:
            operatorId = 97000040,
            locale = "en_GB",
            baseUrl = "https://shared1-staging.iplabs.io/97000040",
            externalCartServiceBaseUrl = "https://external-cart.staging.eu-central-1.iplabs.io",
            localProjectsLocation = filesDir
        )

        // Other code to run during activity creation…
    }

    // Other methods of the activity…
}

Starting the Editor​

To actually see our photo product editor in action, two steps are required. First, you have to integrate a UI control called MobileSdkEditorView into your app’s frontend. This is a really easy and straightforward process, as you just have to add it to the layout XML file, that belongs to a fragment you want to use for hosting the editor:

fragment_editor.xml
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <androidx.constraintlayout.widget.ConstraintLayout
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".fragments.EditorFragment">

        <de.iplabs.mobile_sdk.editor.MobileSdkEditorView
            android:id="@+id/editor"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />
    </androidx.constraintlayout.widget.ConstraintLayout>
</layout>

As a second step you need to get a reference to the editor UI component in your fragment, do some setup around it, and finally initialize it with a few parameters:

  • productConfiguration
    An instance of ProductConfiguration, combining the identifier of the product you want to edit with an optional set of parameters to further specify the desired variant of the product. Both ID and options can be found in the Portfolio.

  • callbacks
    A set of callbacks, in which you define the interaction between the editor and your app.

Two more parameters exist, which allow you to further customize the editor’s look and feel to your needs, in case you wish to do so:

  • editorConfiguration
    An optional set of configuration adjustments to influence the editor’s feature set. See branding docs for details.

  • branding
    An optional set of properties wrapped in the Branding class, used to adjust the photo product editor’s styling to your brand’s look. See branding docs for details.

All this assembled together will look something like this:

EditorFragment.kt
package com.example.yourapp.fragments

import de.iplabs.mobile_sdk.editor.EditorCallbacks
import de.iplabs.mobile_sdk.editor.CartProject
import de.iplabs.mobile_sdk.editor.MobileSdkEditorView
import de.iplabs.mobile_sdk.editor.ProductConfiguration
// Other imports…

class EditorFragment : Fragment() {
    private var _binding: FragmentEditorBinding? = null
    private val binding get() = _binding!!
    private var filePathCallback: ValueCallback<Array<Uri>>? = null
    private var imagePicker =
        registerForActivityResult(ActivityResultContracts.OpenMultipleDocuments()) {
            filePathCallback?.onReceiveValue(it.toTypedArray())
            filePathCallback = null
        }
    private lateinit var editor: MobileSdkEditorView

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        _binding = FragmentEditorBinding.inflate(inflater, container, false)

        editor = binding.editor

        return binding.root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        val callbacks = object : EditorCallbacks {
            override fun getFilePicker(
                multipleFilesMode: Boolean
            ): ActivityResultLauncher<Array<String>> {
                // Connect to your file picker here, updating the
                // filePathsCallback property of the editor with file(s)
                // selected…
            }

            override fun requestSessionId(
                authenticateCallback: (String) -> Unit,
                cancelAuthenticationCallback: () -> Unit
            ) {
                // Retrieve session ID here and answer by triggering matching
                // callback accordingly…
            }

            override fun authenticationFailed(errorMessage: String) {
                // Handle failed authentication here…
            }

            override fun transferCartProject(
                cartProject: CartProject
            ) {
                // Add the project to your cart here…
            }

            override fun editCartProjectFailed(
                reason: CartProjectEditingError
            ) {
                // Handle failures during CartProject editing attempts here…
            }

            override fun handleLoadProjectTapped() {
                // Navigate to an overview page with saved projects here…
            }

            override fun handleCleanTerminationRequest(
                targetDestinationId: Int? = null
            ) {
                // Handle requests to leave the editor without any unsaved work
                // here…
            }

            override fun handleDirtyTerminationRequest(
                targetDestinationId: Int? = null
            ) {
                // Handle requests to leave the editor while it still contains
                // unsaved work here…
            }
        }

        editor.initialize(
            // Just sample data, that must be replaced with your specific
            // data in the end:
            productConfiguration = ProductConfiguration(id = 60001206),
            callbacks = callbacks
        )
    }

    // Other methods of the fragment…
}

This concludes your first insights into the Mobile SDK. Continue below with more in-depth guides on how to properly integrate it into your product presentation, checkout, and user management solutions.