Period Tag for Android app

Introduction

📘
Incoming tags feature is available starting from v2.2.243

You can set a tag regardless of the internet connection. It supports both online and offline modes. All tags contain information about the date and time when it was activated and deactivated. this information stores in SDK and uploads to the platform together with trips once the internet is available.

The method does not return any response. if you want to get information about active tags, you have to register 👉 TagsProcessingListener or 👉 TagsProcessingReceiver .

Manage tags

Get tags

/**
	 * Get tags
	 *
	 * The result of the operation you can get through the registration of [TagsProcessingListener] or [TagsProcessingReceiver].
	 * Check [registerTagsReceiver] and [addTagsProcessingCallback]
	 *
	 * @throws IllegalStateException if [initialize] never called. See also [isInitialized].
	 */
	fun getFutureTrackTags()

Create a new tag

/**
	 * Create a new tag
	 *
	 * The result of the operation you can get through the registration of [TagsProcessingListener] or [TagsProcessingReceiver].
	 * Check [registerTagsReceiver] and [addTagsProcessingCallback]
	 * @param tag tag's name
	 * @param source source of the tag. Optional parameter
	 *
	 * @throws IllegalStateException if [initialize] never called. See also [isInitialized].
	 */
	fun addFutureTrackTag(tag: String?, source: String? = null)

Remove the tag

/**
	 * Remove specified tag
	 *
	 * The result of the operation you can get through the registration of [TagsProcessingListener] or [TagsProcessingReceiver].
	 * Check [registerTagsReceiver] and [addTagsProcessingCallback]
	 * @param tag tag's name
	 *
	 * @throws IllegalStateException if [initialize] never called. See also [isInitialized].
	 */
	fun removeFutureTrackTag(tag: String?)

Remove all tags

/**
	 * Remove all tags.
	 *
	 * The result of the operation you can get through the registration of [TagsProcessingListener] or [TagsProcessingReceiver].
	 * Check [registerTagsReceiver] and [addTagsProcessingCallback]
	 *
	 * @throws IllegalStateException if [initialize] was never called. See also [isInitialized].
	 */
	fun removeAllFutureTrackTags()

Tags Processing Listener

It has 4 in-built methods:

onTagAdd(tag: Tag, activationTime: Long, status: Status) - callback of the addFutureTrackTag method

Parameters:

tag - Tag instance for adding
activationTime - UNIX-timestamp in milliseconds of the tag activation time
status - Status of the operation. Status can be:
Status.SUCCESS when the tag was successfully uploaded to server
Status.OFFLINE when the tag wasn’t uploaded to server (no internet, etc.), but will be sent later (when internet connection will appears)
Status.ERROR_TAG_OPERATION when operation can’t be proceeded on server because tag was already created earlier
Status.ERROR_WRONG_TIME when user sent wrong tme (future)
Status.ERROR_INVALID_TAG_SPECIFIED when tag name is null or empty

onTagRemove(tag: Tag, deactivationTime: Long, status: Status) - callback of the removeFutureTrackTag method

Parameters:

tag - Tag instance for removing
deactivationTime - UNIX-timestamp in milliseconds of the tag deactivation time
status - Status of the operation. Status can be:
Status.SUCCESS when the tag was successfully removed from server
Status.OFFLINE when the operation wasn’t pushed to server (no internet, etc.), but will be sent later (when internet connection will appears)
Status.ERROR_TAG_OPERATION when operation can’t be proceeded on server because tag wasn’t exist
Status.ERROR_WRONG_TIME when user sent wrong tme (future)
Status.ERROR_INVALID_TAG_SPECIFIED when tag name is null or empty

onAllTagsRemove(deactivatedTagsCount: Int, time: Long, status: Status) - callback of the removeAllFutureTrackTags method

Parameters:

deactivatedTagsCount - deactivated tags amount
time - UNIX-timestamp in milliseconds (time of the operation)
status - Status of the operation. Status can be:
Status.SUCCESS "Remove all tags" request successfully proceeded
Status.OFFLINE when the operation wasn’t pushed to server (no internet, etc.), but will be sent later (when internet connection will appear)
Status.ERROR_TAG_OPERATION when operation can’t be proceeded on server
Status.ERROR_WRONG_TIME when user sent wrong time (future)

onGetTags(tags: Array<Tag>?, time: Long, status: Status) - callback of the getFutureTrackTags method

Parameters:

tags - Array? - array of tags. Can be null if status in not SUCCESS
time - UNIX-timestamp in milliseconds (time of the operation)
status - Status of the operation. Status can be:
Status.SUCCESS - success
Status.OFFLINE if there is no internet connection

Sample of using TagsProcessingListener

1. Implement it on your side

val listener = object : TagsProcessingListener {
	override fun onTagAdd(status: Status, tag: Tag, activationTime: Long) {
		runOnUiThread {
			when (status) {
				Status.SUCCESS -> {
					// tag successfully added
				}
				Status.OFFLINE -> {
					// tag was saved to the local storage. It will be sent later when internet will be available
				}
				Status.ERROR_TAG_OPERATION -> {
					// unable to add tag to server (The tag has already been created)
				}
				Status.ERROR_WRONG_TIME -> {
					// Unable to perform operation. Future time specified.
				}
				Status.ERROR_INVALID_TAG_SPECIFIED -> {
					// null or blank tag name specified
				}
			}
		}
	}

	override fun onTagRemove(status: Status, tag: Tag, deactivationTime: Long) {
		runOnUiThread {
			when (status) {
				Status.SUCCESS -> {
					// tag was successfully removed
				}
				Status.OFFLINE -> {
					// tag deactivation was saved to the local storage. It will be sent later when internet will be available
				}
				Status.ERROR_TAG_OPERATION -> {
					// unable to add tag to server (Tag doesn't exist. Unable to remove)
				}
				Status.ERROR_WRONG_TIME -> {
					// Unable to perform operation. Future time specified.
				}
				Status.ERROR_INVALID_TAG_SPECIFIED -> {
					// null or blank tag name specified
				}
			}
		}
	}

	override fun onAllTagsRemove(status: Status, deactivatedTagsCount: Int, time: Long) {
		runOnUiThread {
			when (status) {
				Status.SUCCESS -> {
					// "Remove all tags" request was successfully proceeded
				}
				Status.OFFLINE -> {
					// "Remove all tags" request was saved to the local storage. It will be sent later when internet will be available
				}
				Status.ERROR_TAG_OPERATION -> {
					// unable to proceed on server
				}
				Status.ERROR_WRONG_TIME -> {
					// Unable to perform operation. Future time specified.
				}
			}
		}
	}

	override fun onGetTags(status: Status, tags: Array<Tag>?, time: Long) {
		runOnUiThread {
			when (status) {
				Status.SUCCESS -> {
					// all cached requests (for add/ remove/ remove all tags) were proceeded and tags fetched successfully
				}
				Status.OFFLINE {
					// can't fetch tags list. Try again later
				}
			}
		}
	}
}

2. Add it to the SDK:

TrackingApi.getInstance().addTagsProcessingCallback(listener)

Don’t forget to remove the listener when it’s not needed:

TrackingApi.getInstance().removeTagsProcessingCallback()

Tags processing receiver

TagsProcessingReceiver works the same as TagsProcessingListener. But that is a BroadcastReceiver. Methods are the same. 👉 Methods description.

Sample of using TagsProcessingReceiver

1. Add the following class to your application

class TagsReceiver : TagsProcessingReceiver() {
	override fun onTagAdd(status: Status, tag: Tag, activationTime: Long) {
		when (status) {
			Status.SUCCESS -> {
				// tag successfully added
			}
			Status.OFFLINE -> {
				// tag was saved to the local storage. It will be sent later when internet will be available
			}
			Status.ERROR_TAG_OPERATION -> {
				// unable to add tag to server (The tag has already been created)
			}
			Status.ERROR_WRONG_TIME -> {
        // Unable to perform operation. Future time specified.
      }
      Status.ERROR_INVALID_TAG_SPECIFIED -> {
					// null or blank tag name specified
			}
		}
	}

	override fun onTagRemove(status: Status, tag: Tag, deactivationTime: Long) {
		when (status) {
			Status.SUCCESS -> {
				// tag was successfully removed
			}
			Status.OFFLINE -> {
				// tag deactivation was saved to the local storage. It will be sent later when internet will be available
			}
			Status.ERROR_TAG_OPERATION -> {
				// unable to add tag to server (Tag doesn't exist. Unable to remove)
			}
			Status.ERROR_WRONG_TIME -> {
        // Unable to perform operation. Future time specified.
      }
      Status.ERROR_INVALID_TAG_SPECIFIED -> {
					// null or blank tag name specified
			}
		}
	}

	override fun onAllTagsRemove(status: Status, deactivatedTagsCount: Int, time: Long) {
		when (status) {
			Status.SUCCESS -> {
				// "Remove all tags" request was successfully proceeded
			}
			Status.OFFLINE -> {
				// "Remove all tags" request was saved to the local storage. It will be sent later when internet will be available
			}
			Status.ERROR_TAG_OPERATION -> {
				// unable to proceed on server
			}
			Status.ERROR_WRONG_TIME -> {
        // Unable to perform operation. Future time specified.
      }
		}
	}

	override fun onGetTags(status: Status, tags: Array<Tag>?, time: Long) {
		when(status) {
			Status.SUCCESS -> {
				// all cached requests (for add/ remove/ remove all tags) were proceeded and tags fetched successfully
			}
			Status.OFFLINE -> {
				// can't fetch tags list. Try again later
			}
		}
	}
}

2. Add this broadcast receiver to the manifest before the tag.

<receiver android:name=".TagsReceiver"/>

3. Register it with SDK:

TrackingApi.getInstance().registerTagsReceiver(TagsReceiver::class.java)

4. Don't forget to unregister when it’s not needed:

TrackingApi.getInstance().unregisterTagsReceiver()