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.
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.
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@example.com:liferay/liferay-mobile-sdk.git
Since the Mobile SDK changes frequently, you should check out the Mobile SDK
Builder’s latest stable release.
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-220.127.116.11 tag corresponds to version 18.104.22.168
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
git checkout tags/builder-22.214.171.124 -b builder-126.96.36.199
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!
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.
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
folder. Note that you must also install Liferay’s prebuilt Mobile SDK in your
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
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.
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.