In addition to ecommerce websites, many ecommerce startups now require mobile applications to enhance the shopping experience for users with features such as push notifications, personalization, less friction, and more.
Medusa is a set of ecommerce building blocks that gives developers full control over building an ecommerce application. Its modules make up a headless backend that any frontend, storefront, app, or admin dashboard, can connect to through REST APIs. “Headless” in this case means that the backend and frontend are separate.
This article explains how to build an Android ecommerce app with Medusa. The code source of the Android client is available on GitHub.
Here is a preview of what your application should look like at the end of this tutorial.
Prerequisites
To follow this guide, it's essential to have the following:
- The latest stable version of Node.js
- Yarn, but you can use npm or pnpm as alternatives to yarn if you prefer.
- Android Studio
Set Up Medusa Server
Install the Medusa CLI app with the following command:
Create a new Medusa project:
By default, it will use SQLite database. You can configure it to use PostgreSQL database. Refer to the documentation for the details.
Start the server with the commands below:
Your server runs at port 9000. To verify that the server is working properly, you can open the URL
with your browser. You should get the JSON data of products available on your server.Copy to clipboardhttp://localhost:9000/store/products
Set Up the Android Ecommerce Project
Begin by launching Android Studio and create a new project. In the New Project window, choose Empty Compose Activity.
In the following screen, choose API 33: Android Tiramisu in the Minimum SDK field.
You can name your application and your package as you wish. In this tutorial, the application's name is Medusa Android Application and the package name is
.Copy to clipboardcom.medusajs.android.medusaandroidapplication
Install Dependencies
Once the project is ready, edit the application
and add these libraries in theCopy to clipboardbuild.gradle
block:Copy to clipboarddependencies
Sync the Gradle build file by clicking the
button. The Retrofit library allows you to connect to API with objects, while the Glide library facilitates the loading of remote images. The navigation connects screens in your Android application.Copy to clipboardSync Now
Create an XML file named
insideCopy to clipboardnetwork_security_config.xml
and add the following content:Copy to clipboardapp/res/xml
Add this network rule to connect to your
in the Android emulator without https. The Android emulator recognizesCopy to clipboardlocalhost
as 10.0.2.2.Copy to clipboardlocalhost
Edit
inCopy to clipboardAndroidManifest.xml
. Add these lines inside theCopy to clipboardapp/manifests
node:Copy to clipboardmanifest
Add this line as an attribute in the
node:Copy to clipboardapplication
Connect the Android Project to the Medusa Server
You have to model the object that represents the API in the Medusa Server. Create the package
inCopy to clipboardmodel
. Inside the package, create theCopy to clipboardapp/java/com/medusajs/android/medusaandroidapplication
class, and replace the content with the following code:Copy to clipboardResponse
Each data class represents the JSON data structure you get from or send to the Medusa server. You can take a look at the complete API reference of the Medusa server in this store API reference.
Check if the result of an API call has this structure:
If that is the case, then the correspondence data class are these classes:
You need to access the API endpoints. Create the
interface inCopy to clipboardMedusaService
and replace the content with the following code:Copy to clipboardapp/java/com/medusajs/android/medusaandroidapplication/``model
As you can see, there are two annotations. One is for the GET request and the other is for the POST request. The argument for the annotation is the API endpoint in the Medusa server. The argument
meanCopy to clipboard/store/products
. The return result represents the result type you will get.Copy to clipboardhttp://``localhost:9000``/store/products
The
represents the JSON data you send to the API endpoint. TheCopy to clipboard@Body
represents the parameter of the API endpoint.Copy to clipboard@Path
This is only an interface. You need to implement it. Create the
class inside theCopy to clipboardProductsRetriever
package and replace the content with the following code:Copy to clipboardapp/java/com/medusajs/android/medusaandroidapplication/model
In this class, you initialize the
variable with the base URLCopy to clipboardretrofit
and the Gson converter to handle JSON. Remember that the emulator knows theCopy to clipboardhttp://10.0.2.2:9000
asCopy to clipboardlocalhost
. Then you create a service with theCopy to clipboard10.0.2.2
method from theCopy to clipboardcreate
variable withCopy to clipboardretrofit
.Copy to clipboardMedusaService
You use this
variable within the implemented methods. You execute the method defined in the interface, resulting in the call object. Then you call theCopy to clipboardservice
method from this object with the callback argument. After the API endpoint is called, this callback will be executed.Copy to clipboardenqueue
Products List Screen
Now that you can connect to API endpoints, you can create a UI interface for the products list. Create a new file called
inCopy to clipboardProductsList.kt
and replace the content with the following code:Copy to clipboardapp/java/com/medusajs/android/``medusaandroidapplication``ui
In this
function, you create a button to go to the cart screen and a list of products. Each card is composed of a remote image, a title of the product, and the price.Copy to clipboardProductsList
Each product in Medusa has more than one variant. Each variant can have many prices (depending on which region). For this mobile ecommerce tutorial, each product uses the first variant and the first price from the variant.
The purpose of this decision is to make the tutorial simple. But in production, you can make a different architecture, such as displaying products with their variants.
Product Info Screen
Now it’s time to create a detail page. On that page, a user can add the product to their shopping cart.
Create the
file insideCopy to clipboardProductItem.kt
and replace the content with the following code:Copy to clipboardapp/java/com/medusajs/androidmedusaandroidapplication/ui
In the button's callback, you create an object of
with two methods:Copy to clipboardCallback<CartResult>
andCopy to clipboardonFailure
. If the API call is successful, theCopy to clipboardonResponse
method will be triggered. You callCopy to clipboardonReponse
with the cart id you receive from the server. The method saves the cart id to a variable so you can reuse the cart id later. If the API call is unsuccessful, theCopy to clipboardonCartChange
method will be called. In this case, you just log the error.Copy to clipboardonFailure
You call the
method with the variant id of the product. To simplify the tutorial, you just send the first variant of the product. Then you can only add one piece of the product.Copy to clipboardcreateCart
If you want to add two product units, you must press the button twice. You also send the cart ID. Initially, the cart ID will be 'null’, in which case the server will create a cart for you. However, if it is not null, you will reuse the existing cart, allowing you to add the product.
To create a cart, you call the
method with theCopy to clipboardcreateCart
object. To add an item to the cart, call theCopy to clipboardCartRequest
method with theCopy to clipboardaddProductToCart
object.Copy to clipboardLineItem
You can verify the JSON data the Medusa server requires in the API documentation.
For example, to add a line item, the expected payload is:
Notice the JSON fields (
andCopy to clipboardvariant_id
) are the same as the fields in theCopy to clipboardquantity
data class.Copy to clipboardLineItem
Create a Cart
You need to create the
. CreateCopy to clipboardViewModel
inCopy to clipboardCartViewModel
:Copy to clipboardapp/java/com/medusajs/android/``m``edusaandroidapplication/model
The
hasCopy to clipboardViewModel
that is aCopy to clipboard_cartState
holdingCopy to clipboardMutableStateFlow
.Copy to clipboardCartModel
Users might want to see what products they have added to their shopping cart. You need to create a screen for the cart. Create
inCopy to clipboardCartCompose
and replace its content with the following code:Copy to clipboardapp/java/com/medusajs/android/<your application name>/ui
You use
and aCopy to clipboardcartViewModel
to hold the products you added to the cart.Copy to clipboardViewModel
In the
method, after a successful API call, you set theCopy to clipboardonResponse
with the cart JSON object from the server.Copy to clipboardViewModel
You call the
method with the cart id argument to get the information about the cart.Copy to clipboardgetCart
Set up the Navigation
All that’s left is to create the navigation that connects the screens. Create
insideCopy to clipboardMainAppCompose
and replace the content with the following code:Copy to clipboardapp/java/com/medusajs/ui
You created
, which is composed of three compose functions or screens. You navigate from one screen to another screen with theCopy to clipboardNavHost
method of theCopy to clipboardnavigate
object.Copy to clipboardnavController
Finally, edit
that is inside theCopy to clipboardMainActivity
package to call theCopy to clipboardapp/java/com/medusajs/android/medusaandroidapplication
that connects the screens. Replace the content with the following code:Copy to clipboardMainApp
Test the Application
Now that you have written the code, it's time to build the application. Make sure the Medusa server is running and run the following command:
Build and run the application in the Android emulator. But first, you need to create a device in Device Manager. You will get the screen of the products list.
Click one of the products, then you'll see the product detail page.
Add some products to your shopping cart in the products list screen; click the button to view the cart.
Conclusion
This tutorial provides an overview of how to build an Android ecommerce application with Medusa. This application provides basic functionalities, but you can implement more functionalities to enhance it:
- Add a “region switcher" for customers’ region selection.
- Use product variants to provide product options like colors on the details view.
- Implement authentication flow allowing customers to sign up with their email or log in via social media.
- Implement the full checkout experience when customers confirm the payment.
- Integrate payment methods such as Stripe.
Visit the Medusa store API reference to discover all the possibilities to build your ecommerce application. Or check out our Next.js-based commerce template for your next project.
Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.
Share this post
Try Medusa
Spin up your environment in a few minutes.
