The Liferay Mobile SDK lets you connect your Android and iOS apps to a Liferay Portal instance. By accessing built-in portal services through Liferay’s prebuilt Mobile SDK, your apps can access the out-of-the-box functionality in a Liferay Portal instance. But what if you want to call custom services that belong to a custom portlet? No problem! In this case, you need to build your own Mobile SDK that can call these custom portlet services.
Note that when you build a Mobile SDK for a portlet, it contains only the classes needed to call that portlet’s remote services. You still need to install Liferay’s prebuilt Mobile SDK in your app. It contains the framework required to construct remote service calls in general.
The Liferay Mobile SDK project contains a Mobile SDK Builder that generates a custom Mobile SDK for the Android and iOS platforms. The Mobile SDK Builder does this by generating client libraries that let your native mobile apps invoke a custom portlet’s remote web services. Think of the Mobile SDK Builder as a Service Builder on the client side (click here to learn about Service Builder).
This tutorial covers how to build a custom Mobile SDK for Android and iOS. You’ll begin by making sure the remote services are configured for any custom portlets you have.
Configuring Your Portlet’s Remote Services
For the Mobile SDK Builder to discover a portlet’s remote services, the services must be available and accompanied by a Web Service Deployment Descriptor (WSDD). For instructions on creating a portlet’s remote services and building its WSDD, click here.
Next, you’ll download the Liferay Mobile SDK’s source code.
Downloading the Liferay Mobile SDK
To build a Mobile SDK for your custom portlet’s services, you need to have the Liferay Mobile SDK’s source code on your local machine. This code also contains the Mobile SDK Builder. You can get this code by cloning the Mobile SDK project via Git, or by downloading it from GitHub. To clone the Mobile SDK project with Git, open a terminal and navigate to the directory on your machine in which you want to put the Mobile SDK. Then run this command:
git clone [email protected]:liferay/liferay-mobile-sdk.git
Since the Mobile SDK changes frequently, you should check out the Mobile SDK Builder’s latest stable release. Click here to see the list of available stable releases. Stable builder releases correspond to GitHub tags that begin with builder and end with the builder version. The builder version’s first two digits indicate the compatible Liferay Portal version. For example, the
builder-22.214.171.124 tag corresponds to version 126.96.36.199 of the Liferay Mobile SDK Builder, which is compatible with Liferay Portal 6.2. To check out this tag in a new branch of the same name, you can use this command:
git checkout tags/builder-188.8.131.52 -b builder-184.108.40.206
Alternatively, you can download the ZIP or TAR.GZ file listed under the builder tags on GitHub.
Now you’re ready to build the Mobile SDK!
Building a Liferay Mobile SDK
After you’ve downloaded the Mobile SDK’s source code, you must build the module in which you’ll build your custom portlet’s Mobile SDK. The Mobile SDK Builder comes with a command line wizard that helps you build this module. To start the wizard, run the following command in the builder’s root folder:
This starts the wizard with the most common properties it needs to generate code for your portlet. If you need more control over these properties, run the same command with the
./gradlew createModule -P=all
The wizard should look similar to this screenshot. Note that default values are in square brackets with blue text:
So what properties are available, and what do they do? Fantastic question! You can set the following properties during or after running
createModule. If you want or need to set these properties after running
createModule, you can do so in your module’s
gradle.properties file. The values in parentheses are the keys used in
Context (context): Your portlet’s web context. For example, if you’re generating a Mobile SDK for Liferay Portal’s Calendar portlet, which is generally deployed to the
calendar-portletcontext, then you should set the context value to
calendar-portlet. If there are no services available at the specified context, you may have forgotten to generate your portlet’s WSDD.
Platforms (platforms): The platforms to build the Mobile SDK for. By default, you can generate code for Android and iOS (
Server URL (url): Your Liferay Portal instance’s URL. To discover your services, the Mobile SDK Builder tries to connect to this instance at the specified context.
Filter (filter): Specifies the portlet entities the Mobile SDK can access. A blank value specifies all portlet entity services. For example, the Calendar portlet’s entities include
CalendarResource. To generate a Mobile SDK for only the
CalendarBookingentity, set the filter’s value to
Module Version (version): The version number appended to your Mobile SDK’s JAR (Android) and ZIP files (iOS). The sections on packaging your Mobile SDK explain this further.
Package Name (packageName): On Android, this is the package your Mobile SDK’s classes are written to (iOS doesn’t use packages). Note that the Liferay Portal version is appended to the end of the package name. For example, if you’re using Liferay Portal 6.2 and specify
com.liferay.mobile.androidas the package name, the Mobile SDK Builder appends
v62to the package name, yielding
com.liferay.mobile.android.v62. This prevents collisions between classes with the same name, which lets you use Mobile SDKs for more than one portal version in the same app. You can use the
Portal Versionproperty to change the portal version.
POM Description (description): Your POM file’s description.
Note that there’s also a
destination property that can only be set in the
gradle.properties file. This property specifies the destination for the generated source files. You won’t generally need to change this.
After you set the properties you need, the Mobile SDK Builder generates your module in the folder
Now you can build your Mobile SDK. To do this, navigate to your module and run this command:
By default, the builder writes the source files to
ios/Source in your module’s folder.
If you update your portlet’s remote services on the server side and need to update your Mobile SDK, simply run
../../gradlew generate again.
Awesome! Now you know how to create and regenerate a Mobile SDK for your custom portlet’s remote services. Next, you’ll finish by packaging your Mobile SDK for the Android and iOS.
Packaging Your Mobile SDK for Android
To package your Mobile SDK in a JAR file for use in an Android project, run the following command from your module’s folder:
This packages your Mobile SDK in the following file:
To call your portlet’s remote services, you must first install this file in your Android project. To do so, copy the file into your Android app’s
app/libs folder. Note that you must also install Liferay’s prebuilt Mobile SDK in your app. Click here for instructions on doing this.
Also note that if you regenerate your Mobile SDK to include new functionality, you can update your module’s version in its
gradle.properties file. For example, if you added or changed a service method in the Mobile SDK you initially built, you could update it’s version by setting
version=1.1 in your module’s
To learn how to use the Mobile SDK in your Android app, click here to see the rest of the Android Mobile SDK documentation. You can also use your Mobile SDK to create custom Screenlets in Liferay Screens. Click here to see the Liferay Screens documentation for Android.
Packaging Your Mobile SDK for iOS
To package your Mobile SDK in a ZIP file for use in an iOS project, run the following command from your module’s folder:
This packages your Mobile SDK in the following file:
To call your portlet’s remote services, you must first install this file in your Xcode project. To do so, simply unzip it and add its files to your Xcode project.
To learn how to use the Mobile SDK in your iOS app, click here to see the rest of the iOS Mobile SDK documentation. You can also use your Mobile SDK to create custom Screenlets in Liferay Screens. Click here to see the Liferay Screens documentation for iOS.