Back to project page countly-sdk-android.
The source code is released under:
Copyright (c) 2012, 2013 Countly Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Soft...
If you think the Android project countly-sdk-android listed in this page is inappropriate, such as containing malicious code/tools or violating the copyright, please email info at java2s dot com, thanks.
/* Copyright (c) 2012, 2013, 2014 Countly//from w ww . ja v a2 s . c o m Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ package ly.count.android.api; import java.net.*; import java.util.*; import java.util.concurrent.*; import android.content.Context; /** * This class is the public API for the Countly Android SDK. * Get more details <a href="https://github.com/Countly/countly-sdk-android">here</a>. */ public class Countly { /** * Current version of the Count.ly Android SDK as a displayable string. */ public static final String COUNTLY_SDK_VERSION_STRING = "14.11"; /** * Default string used in the begin session metrics if the * app version cannot be found. */ public static final String DEFAULT_APP_VERSION = "1.0"; /** * Tag used in all logging in the Count.ly SDK. */ public static final String TAG = "Countly"; /** * Determines how many custom events can be queued locally before * an attempt is made to submit them to a Count.ly server. */ private static final int EVENT_QUEUE_SIZE_THRESHOLD = 10; /** * How often onTimer() is called. */ private static final long TIMER_DELAY_IN_SECONDS = 60; // see http://stackoverflow.com/questions/7048198/thread-safe-singletons-in-java private static class SingletonHolder { static final Countly instance = new Countly(); } private ConnectionQueue connectionQueue_; @SuppressWarnings("FieldCanBeLocal") private ScheduledExecutorService timerService_; private EventQueue eventQueue_; private long prevSessionDurationStartTime_; private int activityCount_; private boolean disableUpdateSessionRequests_; private boolean enableLogging_; /** * Returns the Countly singleton. */ public static Countly sharedInstance() { return SingletonHolder.instance; } /** * Constructs a Countly object. * Creates a new ConnectionQueue and initializes the session timer. */ Countly() { connectionQueue_ = new ConnectionQueue(); timerService_ = Executors.newSingleThreadScheduledExecutor(); timerService_.scheduleWithFixedDelay(new Runnable() { @Override public void run() { onTimer(); } }, TIMER_DELAY_IN_SECONDS, TIMER_DELAY_IN_SECONDS, TimeUnit.SECONDS); } /** * Initializes the Countly SDK. Call from your main Activity's onCreate() method. * Must be called before other SDK methods can be used. * Device ID is supplied by OpenUDID service, see <a href="https://github.com/Countly/countly-sdk-android">Countly</a> for instructions. * @param context application context * @param serverURL URL of the Countly server to submit data to; use "https://cloud.count.ly" for Countly Cloud * @param appKey app key for the application being tracked; find in the Countly Dashboard under Management > Applications * @throws java.lang.IllegalArgumentException if context, serverURL, appKey, or deviceID are invalid * @throws java.lang.IllegalStateException if the Countly SDK has already been initialized */ public Countly init(final Context context, final String serverURL, final String appKey) { return init(context, serverURL, appKey, null, null); } /** * Initializes the Countly SDK. Call from your main Activity's onCreate() method. * Must be called before other SDK methods can be used. * @param context application context * @param serverURL URL of the Countly server to submit data to; use "https://cloud.count.ly" for Countly Cloud * @param appKey app key for the application being tracked; find in the Countly Dashboard under Management > Applications * @param deviceID unique ID for the device the app is running on; note that null in deviceID means that Countly will fall back to OpenUDID, then, if it's not available, to Google Advertising ID * @return Countly instance for easy method chaining * @throws java.lang.IllegalArgumentException if context, serverURL, appKey, or deviceID are invalid * @throws java.lang.IllegalStateException if init has previously been called with different values during the same application instance */ public Countly init(final Context context, final String serverURL, final String appKey, final String deviceID) { return init(context, serverURL, appKey, deviceID, null); } /** * Initializes the Countly SDK. Call from your main Activity's onCreate() method. * Must be called before other SDK methods can be used. * @param context application context * @param serverURL URL of the Countly server to submit data to; use "https://cloud.count.ly" for Countly Cloud * @param appKey app key for the application being tracked; find in the Countly Dashboard under Management > Applications * @param deviceID unique ID for the device the app is running on; note that null in deviceID means that Countly will fall back to OpenUDID, then, if it's not available, to Google Advertising ID * @param idMode enum value specifying which device ID generation strategy Countly should use: OpenUDID or Google Advertising ID * @return Countly instance for easy method chaining * @throws java.lang.IllegalArgumentException if context, serverURL, appKey, or deviceID are invalid * @throws java.lang.IllegalStateException if init has previously been called with different values during the same application instance */ public synchronized Countly init(final Context context, final String serverURL, final String appKey, final String deviceID, DeviceId.Type idMode) { if (context == null) { throw new IllegalArgumentException("valid context is required"); } if (!isValidURL(serverURL)) { throw new IllegalArgumentException("valid serverURL is required"); } if (appKey == null || appKey.length() == 0) { throw new IllegalArgumentException("valid appKey is required"); } if (deviceID != null && deviceID.length() == 0) { throw new IllegalArgumentException("valid deviceID is required"); } if (deviceID == null && idMode == null) { if (OpenUDIDAdapter.isOpenUDIDAvailable()) idMode = DeviceId.Type.OPEN_UDID; else if (AdvertisingIdAdapter.isAdvertisingIdAvailable()) idMode = DeviceId.Type.ADVERTISING_ID; } if (deviceID == null && idMode == DeviceId.Type.OPEN_UDID && !OpenUDIDAdapter.isOpenUDIDAvailable()) { throw new IllegalArgumentException("valid deviceID is required because OpenUDID is not available"); } if (deviceID == null && idMode == DeviceId.Type.ADVERTISING_ID && !AdvertisingIdAdapter.isAdvertisingIdAvailable()) { throw new IllegalArgumentException("valid deviceID is required because Advertising ID is not available (you need to include Google Play services 4.0+ into your project)"); } if (eventQueue_ != null && (!connectionQueue_.getServerURL().equals(serverURL) || !connectionQueue_.getAppKey().equals(appKey) || !DeviceId.deviceIDEqualsNullSafe(deviceID, idMode, connectionQueue_.getDeviceId()) )) { throw new IllegalStateException("Countly cannot be reinitialized with different values"); } // if we get here and eventQueue_ != null, init is being called again with the same values, // so there is nothing to do, because we are already initialized with those values if (eventQueue_ == null) { DeviceId deviceIdInstance; if (deviceID != null) { deviceIdInstance = new DeviceId(deviceID); } else { deviceIdInstance = new DeviceId(idMode); } final CountlyStore countlyStore = new CountlyStore(context); deviceIdInstance.init(context, countlyStore, true); connectionQueue_.setServerURL(serverURL); connectionQueue_.setAppKey(appKey); connectionQueue_.setCountlyStore(countlyStore); connectionQueue_.setDeviceId(deviceIdInstance); eventQueue_ = new EventQueue(countlyStore); } // context is allowed to be changed on the second init call connectionQueue_.setContext(context); return this; } /** * Immediately disables session & event tracking and clears any stored session & event data. * This API is useful if your app has a tracking opt-out switch, and you want to immediately * disable tracking when a user opts out. The onStart/onStop/recordEvent methods will throw * IllegalStateException after calling this until Countly is reinitialized by calling init * again. */ public synchronized void halt() { eventQueue_ = null; final CountlyStore countlyStore = connectionQueue_.getCountlyStore(); if (countlyStore != null) { countlyStore.clear(); } connectionQueue_.setContext(null); connectionQueue_.setServerURL(null); connectionQueue_.setAppKey(null); connectionQueue_.setCountlyStore(null); prevSessionDurationStartTime_ = 0; activityCount_ = 0; } /** * Tells the Countly SDK that an Activity has started. Since Android does not have an * easy way to determine when an application instance starts and stops, you must call this * method from every one of your Activity's onStart methods for accurate application * session tracking. * @throws IllegalStateException if Countly SDK has not been initialized */ public synchronized void onStart() { if (eventQueue_ == null) { throw new IllegalStateException("init must be called before onStart"); } ++activityCount_; if (activityCount_ == 1) { onStartHelper(); } } /** * Called when the first Activity is started. Sends a begin session event to the server * and initializes application session tracking. */ void onStartHelper() { prevSessionDurationStartTime_ = System.nanoTime(); connectionQueue_.beginSession(); } /** * Tells the Countly SDK that an Activity has stopped. Since Android does not have an * easy way to determine when an application instance starts and stops, you must call this * method from every one of your Activity's onStop methods for accurate application * session tracking. * @throws IllegalStateException if Countly SDK has not been initialized, or if * unbalanced calls to onStart/onStop are detected */ public synchronized void onStop() { if (eventQueue_ == null) { throw new IllegalStateException("init must be called before onStop"); } if (activityCount_ == 0) { throw new IllegalStateException("must call onStart before onStop"); } --activityCount_; if (activityCount_ == 0) { onStopHelper(); } } /** * Called when final Activity is stopped. Sends an end session event to the server, * also sends any unsent custom events. */ void onStopHelper() { connectionQueue_.endSession(roundedSecondsSinceLastSessionDurationUpdate()); prevSessionDurationStartTime_ = 0; if (eventQueue_.size() > 0) { connectionQueue_.recordEvents(eventQueue_.events()); } } /** * Records a custom event with no segmentation values, a count of one and a sum of zero. * @param key name of the custom event, required, must not be the empty string * @throws IllegalStateException if Countly SDK has not been initialized * @throws IllegalArgumentException if key is null or empty */ public void recordEvent(final String key) { recordEvent(key, null, 1, 0); } /** * Records a custom event with no segmentation values, the specified count, and a sum of zero. * @param key name of the custom event, required, must not be the empty string * @param count count to associate with the event, should be more than zero * @throws IllegalStateException if Countly SDK has not been initialized * @throws IllegalArgumentException if key is null or empty */ public void recordEvent(final String key, final int count) { recordEvent(key, null, count, 0); } /** * Records a custom event with no segmentation values, and the specified count and sum. * @param key name of the custom event, required, must not be the empty string * @param count count to associate with the event, should be more than zero * @param sum sum to associate with the event * @throws IllegalStateException if Countly SDK has not been initialized * @throws IllegalArgumentException if key is null or empty */ public void recordEvent(final String key, final int count, final double sum) { recordEvent(key, null, count, sum); } /** * Records a custom event with the specified segmentation values and count, and a sum of zero. * @param key name of the custom event, required, must not be the empty string * @param segmentation segmentation dictionary to associate with the event, can be null * @param count count to associate with the event, should be more than zero * @throws IllegalStateException if Countly SDK has not been initialized * @throws IllegalArgumentException if key is null or empty */ public void recordEvent(final String key, final Map<String, String> segmentation, final int count) { recordEvent(key, segmentation, count, 0); } /** * Records a custom event with the specified values. * @param key name of the custom event, required, must not be the empty string * @param segmentation segmentation dictionary to associate with the event, can be null * @param count count to associate with the event, should be more than zero * @param sum sum to associate with the event * @throws IllegalStateException if Countly SDK has not been initialized * @throws IllegalArgumentException if key is null or empty, count is less than 1, or if * segmentation contains null or empty keys or values */ public synchronized void recordEvent(final String key, final Map<String, String> segmentation, final int count, final double sum) { if (eventQueue_ == null) { throw new IllegalStateException("Countly.sharedInstance().init must be called before recordEvent"); } if (key == null || key.length() == 0) { throw new IllegalArgumentException("Valid Countly event key is required"); } if (count < 1) { throw new IllegalArgumentException("Countly event count should be greater than zero"); } if (segmentation != null) { for (String k : segmentation.keySet()) { if (k == null || k.length() == 0) { throw new IllegalArgumentException("Countly event segmentation key cannot be null or empty"); } if (segmentation.get(k) == null || segmentation.get(k).length() == 0) { throw new IllegalArgumentException("Countly event segmentation value cannot be null or empty"); } } } eventQueue_.recordEvent(key, segmentation, count, sum); sendEventsIfNeeded(); } /** * Sets information about user. Possible keys are: * <ul> * <li> * name - (String) providing user's full name * </li> * <li> * username - (String) providing user's nickname * </li> * <li> * email - (String) providing user's email address * </li> * <li> * org - (String) providing user's organization's name where user works * </li> * <li> * phone - (String) providing user's phone number * </li> * <li> * picture - (String) providing WWW URL to user's avatar or profile picture * </li> * <li> * picturePath - (String) providing local path to user's avatar or profile picture * </li> * <li> * gender - (String) providing user's gender as M for male and F for female * </li> * <li> * byear - (int) providing user's year of birth as integer * </li> * </ul> * @param data Map<String, String> with user data */ public synchronized void setUserData(Map<String, String> data) { setUserData(data, null); } /** * Sets information about user with custom properties. * In custom properties you can provide any string key values to be stored with user * Possible keys are: * <ul> * <li> * name - (String) providing user's full name * </li> * <li> * username - (String) providing user's nickname * </li> * <li> * email - (String) providing user's email address * </li> * <li> * org - (String) providing user's organization's name where user works * </li> * <li> * phone - (String) providing user's phone number * </li> * <li> * picture - (String) providing WWW URL to user's avatar or profile picture * </li> * <li> * picturePath - (String) providing local path to user's avatar or profile picture * </li> * <li> * gender - (String) providing user's gender as M for male and F for female * </li> * <li> * byear - (int) providing user's year of birth as integer * </li> * </ul> * @param data Map<String, String> with user data * @param customdata Map<String, String> with custom key values for this user */ public synchronized void setUserData(Map<String, String> data, Map<String, String> customdata) { UserData.setData(data); if(customdata != null) UserData.setCustomData(customdata); connectionQueue_.userData(); } /** * Disable periodic session time updates. * By default, Countly will send a request to the server each 30 seconds with a small update * containing session duration time. This method allows you to disable such behavior. * Note that event updates will still be sent every 10 events or 30 seconds after event recording. * @param disable whether or not to disable session time updates */ public synchronized Countly setDisableUpdateSessionRequests(final boolean disable) { disableUpdateSessionRequests_ = disable; return this; } /** * Sets whether debug logging is turned on or off. Logging is disabled by default. * @param enableLogging true to enable logging, false to disable logging */ public synchronized Countly setLoggingEnabled(final boolean enableLogging) { enableLogging_ = enableLogging; return this; } public synchronized boolean isLoggingEnabled() { return enableLogging_; } /** * Submits all of the locally queued events to the server if there are more than 10 of them. */ void sendEventsIfNeeded() { if (eventQueue_.size() >= EVENT_QUEUE_SIZE_THRESHOLD) { connectionQueue_.recordEvents(eventQueue_.events()); } } /** * Called every 60 seconds to send a session heartbeat to the server. Does nothing if there * is not an active application session. */ synchronized void onTimer() { final boolean hasActiveSession = activityCount_ > 0; if (hasActiveSession) { if (!disableUpdateSessionRequests_) { connectionQueue_.updateSession(roundedSecondsSinceLastSessionDurationUpdate()); } if (eventQueue_.size() > 0) { connectionQueue_.recordEvents(eventQueue_.events()); } } } /** * Calculates the unsent session duration in seconds, rounded to the nearest int. */ int roundedSecondsSinceLastSessionDurationUpdate() { final long currentTimestampInNanoseconds = System.nanoTime(); final long unsentSessionLengthInNanoseconds = currentTimestampInNanoseconds - prevSessionDurationStartTime_; prevSessionDurationStartTime_ = currentTimestampInNanoseconds; return (int) Math.round(unsentSessionLengthInNanoseconds / 1000000000.0d); } /** * Utility method to return a current timestamp that can be used in the Count.ly API. */ static int currentTimestamp() { return ((int)(System.currentTimeMillis() / 1000l)); } /** * Utility method for testing validity of a URL. */ static boolean isValidURL(final String urlStr) { boolean validURL = false; if (urlStr != null && urlStr.length() > 0) { try { new URL(urlStr); validURL = true; } catch (MalformedURLException e) { validURL = false; } } return validURL; } // for unit testing ConnectionQueue getConnectionQueue() { return connectionQueue_; } void setConnectionQueue(final ConnectionQueue connectionQueue) { connectionQueue_ = connectionQueue; } ExecutorService getTimerService() { return timerService_; } EventQueue getEventQueue() { return eventQueue_; } void setEventQueue(final EventQueue eventQueue) { eventQueue_ = eventQueue; } long getPrevSessionDurationStartTime() { return prevSessionDurationStartTime_; } void setPrevSessionDurationStartTime(final long prevSessionDurationStartTime) { prevSessionDurationStartTime_ = prevSessionDurationStartTime; } int getActivityCount() { return activityCount_; } boolean getDisableUpdateSessionRequests() { return disableUpdateSessionRequests_; } }