The first step is to add the following permissions to your
For every app you add on Liquid, two versions of the app are created: a production and a development version. These versions have completely distinct environments (i.e., different users, devices, sessions, events, targets and dynamic variables) and each app version has its own API key.
Once you’ve set up the permissions, you must initialize the Liquid singleton (once per app launch) with your App’s API key. Typically, the best place to do this is on the
public void onCreate() method in your Application class.
You can find your App API key on the App Settings of Liquid’s dashboard.
From this moment on, each time you want to call a Liquid method you can do:
All interactions using Liquid SDK should be done using this shared instance of
Liquid object (and not using
Android SDK < 14
If your application supports Android SDK < 14, then you have to notify Liquid when your activity lifecycle changes. On the other hand, for Android SDK versions greater or equal than 14, Liquid will automatically do that for you.
In order to keep track of a specific user between different sessions and devices (or different app installations) you must identify it with a unique identifier. This will allow you to use analytics based on their information.
This identifier is usually a strong UUID, e.g:
"02318f2cdd156d78fd4431". We recommend using your back-end database ID to identify a user. Alternatively, you can use an email or username, provided they cannot be changed.
Tipically, you know more about your user than only his identifier. Liquid allows you to create analytics based on this information through Key-Value user attributes (on a
For each of the above situations, you should identify your user with one of the following two methods, respectively:
It is not mandatory to the user attributes at the moment of user identification. You can set their attributes later using setter methods.
Liquid SDK keeps a cache of your previously identified user. This means that you don’t need to identify your user each time your app is open.
If you never identify your user, all activity will be tracked anonymously. As soon as a user is identified, all that anonymous activity will be automatically aliased to the identified user. This means that you’ll no longer see the anonymous user, but the identified one.
This process of user aliasing is automatic, is the default behavior and is higly recommended that you alias your users. However, if you don’t want this behavior, you may append the prefix
alias:false when identifying your user, like shown in the following example:
Our recommendation is to keep your users identified as much as you can, even after they logout. This will ease the analysis of their behaviour. However, if for any reason you really want to turn the SDK back to the anonymous state, you can use the method
Liquid.getInstance().resetUser();. This will create a new anonymous user (with a new Unique ID and no custom attributes). If your user is already anonymous, this will only wipe their attributes, leaving the unique_id intact.
Probably the most important entity of analytics is an event. Events can be anything you want in the context of your application. It can be a click on a button, a product that is bought or any other interaction. Events are identified by a unique name, and can (optionally) have attributes (Key-Value).
Event names should have a minimum length of 3 characters and a maximum of 50. Also note that Liquid uses the attribute
name to store the event name. If you set a custom event attribute with the key
name it will be overrided by the SDK.
You can track an event anytime you want on your code, using one of the following methods:
Track your Monetization metrics
In order to take advantage of the Monetization section of the Dashboard view, you have to send a
price attribute on your events, make sure to check the Monetization settings section for detailed information.
User attributes are Key-Value objects stored in the form of a
Data types of these attributes can be:
An example that includes all this attributes could be:
You should not store nothing more than user information on this collection, i.e. do not store information related with the device (like model or carrier). This information is stored on the device entity, as explained below.
Information about the user device is automatically saved by Liquid SDK.
You don’t need to worry about tracking information of the device. The following device attributes are always included on analytics (example):
If you have information about user geolocation (a
Location) you can use Liquid to track device location. All you need to do is to inform Liquid SDK about current device location using the following method:
Liquid doesn’t automatically track location changes. This means you’re responsible to inform Liquid SDK each time device location changes.
From this moment on, all data points sent to Liquid will include
longitude attributes associated to Device entity.
To send push notifications and in-app messages to your users through Liquid’s formulas you’ll need to add some code that registers your device with Liquid and GCM (Google Cloud Messaging)
If you don’t have a GCM Sender ID, please visit the tutorial about setting up GCM. The GCM Sender ID is the project number in the Google Console and should look something like “670330094152”.
Then, add it to Liquid’s instance:
Install via Gradle
Add the dependency to your project-level build.gradle:
Add the plugin and the dependency to your app-level build.gradle file:
Add Permissions to Application Manifest
The following permissions are required, replace
YOUR_APP_PACKAGE_NAME with your own app package name.:
Next, register the Google receiver and the Liquid’s message handling service adding the following snippet inside the
Android devices with an SDK version older than 8.0 cannot receive Google Cloud Messaging notifications.
If you already have your own mechanism to send push notifications, you just need to inform Liquid of your user GCM Registration ID, like this:
Payload in push notifications
Liquid sends the following payload to Android devices:
- Title -
- Message -
- Sound -
If add custom JSON, it will be merged to the root of the payload.
Your JSON will have priority over the default keys (lqd_*).
Custom icon in notifications
If you want to add a custom icon to your notification, add the following meta-data inside the
<application> tag and place your custom icon inside the drawable folder.
Configure GCM Sender ID
To send Push Notifications as your App, Liquid must authenticate with Google GCM, using your App’s GCM Auth Key.
Check Setup push notifications certificates section to know how to import it to Liquid dashboard.
Based on variable names, Liquid returns values on five different data types:
boolean. These methods return the
fallbackValue if the value is not present or valid.
You should always define fallback values for your dynamic variables. This will avoid strange behaviors in cases where your app is first launched without an Internet connection, but also if you accidentally delete a variable in Liquid dashboard, or define a different data type between your code and Liquid dashboard.
Each time you use a dynamic variable, you can define its fallback value in the methods:
To ease the development process, each time you use a dynamic variable, its fallback value will be sent to Liquid dashboard and stored as default value (only when your app is compiled with Liquid in development mode).
If you use more than a variable for a Target (defined on Liquid dashboard), all variables affected by that target become dependant on each others.
This means that, if a variable value is fallen back, all the other variables on the same Target will be also fallen back.
Situations like these will only occur if you do something really wrong in your variable settings (e.g. data type mismatch between code and Liquid dashboard), but this mechanism will ensure consistency in your app.
Each time your app is open or closed/paused, new values are requested to Liquid. However, they are not immediately loaded by the SDK as it could cause strange behaviors in front of user eyes. By default, when new values are available, they will only be loaded the next time your app is open.
You can change this behavior just by setting
AutoLoadVariables variable to
YES after initializing Liquid singleton:
Optionaly, you can be notified of Liquid’s internal events by implementing
LiquidOnEventListener interface on your code, to take action when:
- When values are received from Liquid dashboard (not necessarily loaded)
- When values are loaded
As an example, let’s assume you want to take action in your activity, then you should implement the
LiquidOnEventListener interface like this:
and your implementation file should be like this:
Most of the times, it is useful to have all dynamic variables and their fallback values in the same place.
This kind of practice not only improves code organization and readability, but also reutilization of static values in your code.
This way, we recommend you to create a static class file, like:
By doing that you easily change the default variables without changing all activities, like:
while keeping a list of your dynamic variables and fallback values in one unique place.
Most of the times, you’ll want to make sure that your default values (in Liquid dashboard) are the same as the fallback values (in your code).
Liquid needs to authenticate with the Google Cloud Messaging service in order to send push notifications to your users. We have prepared a step-by-step guide to help you get a GCM key and set it up on your app settings, but if you already have a GCM authentication key go directly to the last step.
Set up your GCM auth key
Go to Google Developers Console and create a project for your app if you haven’t already.
Write your project’s name and click create.
Then follow this link to enable Google Services for your app and get a configuration file for your project. Choose your app name from your Developer Console. Enter the package name of your application and Continue.
Select Cloud Messaging and enable it.
After enabling it you will get your Server API Key and Sender ID.
Continue to generate configuration file. Download google-service.json and copy it in the
mobile/module directory in your Android project or in your application’s root folder.
Finally copy the Server API Key into the Notification Settings in your App Settings page in Liquid.
Besides adding your Server API Key to our platform, you need to prepare your Android app to correctly parse Push Notifications sent by us. This is a technical step that involves changing the code on your app; if you haven’t done so, follow the steps on the Setup push notifications and in-app messages section.
On the Dashboard section (check the demo) you will find your app’s Monetization metrics (Conversions, Purchases and Revenue) for the last 30 days. In order to set these values properly follow the guide bellow.
A conversion can be any event (such as a purchase or a sign-up) that you consider important in the context of your app. You can pick up to 5 events and you’ll instantly get insights on how these events performed (converted) in the last 30 days:
- click on Settings and select up to 5 events that you consider to be a conversion
Every event that has the attribute
price is automatically considered a purchase.
An example would be:
The sum of all values (integer) of the attribute
price included on all events.
If you’re already using AppsFlyer in your app, you can view the user acquisition source on Liquid following this guide:
- On your app, after initializing our SDK set AppsFlyer customer user id to Liquid
- Select Liquid on the AppsFlyer integration menu, they’ll ask for your Liquid App key that is available in your app settings page.