Using the Tag API in Android
Tags are not available for DMC customers yet (coming soon)
A tag is used to label users with different elements of the app's business logic.
For example, if your app is intended for pet owners, you can define the different pets as tags ("Dog", "Cat", “Parrot” etc.) and then label users with different tags, depending on the pets they own.
Tags are a useful way to create Segments: Groups of devices that share the same parameters (in this case, the tag values).
You can then send Push notifications to the relevant segments (for example, one notification for dog owners and another for cat owners).
The Tag API enables you to perform actions on tags, both on the application level and on the device level:
- Application tag list – this is the global tag list, common to all devices that use your application.
In the pet owner example, the application tag list includes all the available animals: "Dog", "Cat", “Parrot” etc.
To use tags, the application tag list must be locally stored in the app. To get this list, your code must call the "getTagList" method at least once.
If an updated list is required by the code logic, recall this method wherever tags are used. - Device tag list – this is the local tag list, which is specific to each device.
For example, in the pet owner application, one device tag list may include the "Dog" and "Cat" tags, while another device tag list may include the “Cat” and "Parrot" tags.
All the Tag API methods are callable through Appoxee.methodName, since they are all public static methods.
Before using tags in your code, you must first list all tags required by your application on the Appoxee website,
under Applications->yourAppName-> Tags.
Using unlisted tags in your code during runtime will throw an exception!
- To add tags at any later stage, you must first add them to your application on the Appoxee website.
- To make sure the application uses the most updated tag list, your code must call the "getTagList" method (described below) wherever tags are used.
Since Appoxee.setup() is an Asynchronous Initialisation method, any set action can be performed only after the call Appoxee.isReady()==True. Only after Appoxee.Setup() finished, the flag is set to TRUE value. It is recommended to check the flag before calling setters.
Using Tags API Methods must be done under AsyncTask. For example :
new AsyncTask<Void, Void, Void>() {
ArrayList<String> deviceTags;
@Override
protected void onPreExecute() {
//Do what you need before executing, Progress Bar init etc.
}
@Override
protected Void doInBackground(Void... params) {
// get all tags
allTags = Appoxee.getTagList();
Utils.Debug("Got Application Tag List = " + allTags);
deviceTags = Appoxee.getDeviceTags();
Utils.Debug("Got Device Tag List = " + deviceTags);
if (allTags == null)
allTags = new ArrayList<String>();
if (deviceTags == null)
deviceTags = new ArrayList<String>();
return null;
}
@Override
protected void onPostExecute(Void result) {
//Do What you need with the Data, Dismiss Progress Bar etc.
}
}.execute();
Tag API Methods
addTagsToDevice
Adds the specified tags to the device.
Syntax
public static boolean addTagsToDevice(ArrayList<String> tags) |
Parameters
ArrayList – a string array of tags to be added to the device.
Returns
true if the specified tags were added successfully; false otherwise.
removeTagsFromDevice
Removes the specified tags from the device.
Syntax
public static boolean removeTagsFromDevice(ArrayList<String> tags) |
Parameters
ArrayList – a string array of tags to be removed from the device.
Returns
true if the specified tags were removed successfully; false otherwise.
getDeviceTags
Gets the current device tag list from the server.
Syntax
public static ArrayList<String> getDeviceTags() |
Parameters
ArrayList – a string array of device tags to be returned from the server.
Returns
true if the device’s tag list is returned successfully from the server; false if the operation failed.
If the device has no tags, the returned array has 0 elements.
getTagList
Gets the application's tag list from server.
The application's tag list is the global list of tags defined on the Appoxee website. In order to use the Tag API in the app, this method must be called at least once (usually as part of the registration process).
Call this method in the following cases:
- To activate the Tag API, by getting the initial application tag list from the server.
- To update the local copy of the application tag list on the device.
The application tag list cannot be changed locally and tags cannot be added to it via code.
To update the global list prior to updating the local copy (on the device), you must login to your Appoxee account, and make the required changes
Syntax
public static ArrayList<String> getTagList() |
Parameters
ArrayList – a string array of the application tags to be returned from the server.
Returns
true if the application’s tag list is returned successfully from the server; false otherwise.
If no application tag list was defined on the Appoxee website before the coding process, the returned array will be empty.
cleanTagCache
Clears the local list of device tags from the device cache (the global application tag list cannot be deleted).
Syntax
public static boolean cleanTagCache() |
Returns
true if the local list of device tags was successfully deleted from the device cache; false otherwise.