Added event priorities and provider event priority filtering. Removed explicit provider inclusion.

Author: John Hunt

.idea/gradle.xml

@@ -15,7 +15,7 @@ allprojects {
 In your module's build.gradle file, add the dependency:
 ```groovy
 dependencies {
-		compile 'com.github.busybusy.AnalyticsKit-Android:analyticskit:0.4.0'
+		compile 'com.github.busybusy.AnalyticsKit-Android:analyticskit:0.5.0'
         ...
 	}
 ```
@@ -24,7 +24,7 @@ You can include the implemented providers you want by adding them to the same de
 ```groovy
 dependencies {
 		...
-        compile 'com.github.busybusy.AnalyticsKit-Android:answers-provider:0.4.0'
+        compile 'com.github.busybusy.AnalyticsKit-Android:answers-provider:0.5.0'
 	}
 ```
 
@@ -53,24 +53,33 @@ new ContentViewEvent()
     .send();
 ```
 
-You can restrict events only to certain providers:
+### Event Priorities
+By default, AnalyticsEvent objects have priority 0. However, you can
+set any integer priority on your events. It is up to you to decide on your priority scheme 
+and provider filtering.
 ```java
-new AnalyticsEvent(PredefinedEvents.ADD_TO_CART)
-    .addProvider(Providers.ANSWERS)
-    .putAttribute(Attributes.AddToCart.ITEM_PRICE, BigDecimal.valueOf(17.99))
-    .putAttribute(Attributes.AddToCart.CURRENCY, Currency.getInstance("USD"))
-    .putAttribute(Attributes.AddToCart.ITEM_NAME, "Android T-shirt")
-    .putAttribute(Attributes.AddToCart.ITEM_TYPE, "Clothing")
-    .putAttribute(Attributes.AddToCart.ITEM_ID, "sku-01443")
-    .send();
-    
-new AnalyticsEvent("Google and Mixpanel only Event")
-    .addProvider(Providers.GOOGLE_ANALYTICS)
-    .addProvider(Providers.MIXPANEL)
-    .putAttribute("key", "value")
+new AnalyticsEvent("Readme Read Event")
+    .putAttribute("read", true)
+    .setPriority(7)
     .send();
 ```
 
+By default, providers will log all events regardless of priority. If desired, you can 
+configure providers with a ```PriorityFilter``` so that only events that pass the 
+```PriorityFilter```'s shouldLog() filter method will be logged by that provider. 
+In the following example, only AnalyticsEvent objects with priority less than 10 will be 
+logged by the Answers provider:
+```java
+answersProvider.setPriorityFilter(new AnalyticsKitProvider.PriorityFilter()
+{
+    @Override
+    public boolean shouldLog(int priorityLevel)
+    {
+        return priorityLevel < 10;
+    }
+});
+```
+
 ## License
 
     Licensed under the Apache License, Version 2.0 (the "License");

.idea/modules.xml

@@ -96,6 +96,6 @@
     <orderEntry type="sourceFolder" forTests="false" />
     <orderEntry type="library" exported="" scope="TEST" name="hamcrest-core-1.3" level="project" />
     <orderEntry type="library" exported="" scope="TEST" name="junit-4.12" level="project" />
-    <orderEntry type="library" exported="" name="support-annotations-23.2.0" level="project" />
+    <orderEntry type="library" exported="" name="support-annotations-23.2.1" level="project" />
   </component>
 </module>

.idea/runConfigurations/Unit_Tests___Analytics_Kit.xml

@@ -30,7 +30,7 @@ public class AnalyticsEvent
 	final String name;
 	HashMap<String, Object> attributes;
 	boolean timed;
-	int providersMask = 0;
+	int priorityLevel = 0;
 
 	/**
 	 * Instantiates a new {@code AnalyticsEvent} object
@@ -75,36 +75,24 @@ public AnalyticsEvent putAttribute(@NonNull String attributeName, @NonNull Objec
 	}
 
 	/**
-	 * Restricts this event from being sent to all registered analytics providers.
-	 * <p/>
-	 * For example, if you have five registered providers, but only want to send this event to Google Analytics, call
-	 *                      {@code specifyProviders(Providers.GOOGLE_ANALYTICS)}. To send this event to only Google Analytics and Answers,
-	 *                      call {@code specifyProviders(Providers.GOOGLE_ANALYTICS | Providers.ANSWERS)}.
-	 *
-	 * @param providersMask an int value that contains the bitwise OR of the provider(s) to which you DO wish to send the event.
-	 *
-	 * @return the {@link AnalyticsEvent} instance
+	 * Gets the priority of this event.
+	 * @return the priority of the event. Returns {@code 0} when {@link #setPriority(int)} has not been called.
 	 */
-	@NonNull
-	public AnalyticsEvent specifyProviders(int providersMask)
+	public int getPriority()
 	{
-		this.providersMask = providersMask;
-
-		return this;
+		return priorityLevel;
 	}
 
 	/**
-	 * Specifies a certain provider to which this event will be sent (restricts this event from being sent to all registered analytics providers).
+	 * Sets the priority of the event. The event defaults to {@code 0} when this method is not called.
 	 * <p/>
-	 * For example, if you have five registered providers, but only want to send this event to Google Analytics, call
-	 *                      {@code event.addProvider(Providers.GOOGLE_ANALYTICS)}. To send this event to only Google Analytics and Answers,
-	 *                      call {@code event.addProvider(Providers.GOOGLE_ANALYTICS).addProvider(Providers.ANSWERS)}.
-	 * @param providerMask an int value that contains the type of provider to which you DO wish to send the event.
-	 * @return the {@link AnalyticsEvent} instance
+	 * <b>Note:</b> It is up to the developer to define what priority scheme to use (if any).
+	 * @param priorityLevel the priority the event should use
+	 * @return the {@link AnalyticsEvent} instance (for builder-style convenience)
 	 */
-	public AnalyticsEvent addProvider(int providerMask)
+	public AnalyticsEvent setPriority(int priorityLevel)
 	{
-		this.providersMask |= providerMask;
+		this.priorityLevel = priorityLevel;
 		return this;
 	}
 

README.md

@@ -74,7 +74,7 @@ public AnalyticsKit registerProvider(@NonNull AnalyticsKitProvider provider)
 	 * Sends the given event to all registered analytics providers (OR just to select providers if the event has been set to restrict the providers).
 	 * @param event the event to capture with analytics tools
 	 */
-	public void logEvent(AnalyticsEvent event)
+	public void logEvent(AnalyticsEvent event) throws IllegalStateException
 	{
 		if (event.isTimed())
 		{
@@ -91,20 +91,18 @@ public void logEvent(AnalyticsEvent event)
 		{
 			for (AnalyticsKitProvider provider : providers)
 			{
-				if (event.providersMask != 0)
+				// guard clause
+				//noinspection ConstantConditions
+				if (provider.getPriorityFilter() == null)
 				{
-					// the user has chosen to restrict the providers to which this event is sent
-					if ((provider.getType() & event.providersMask) != 0)
-					{
-						provider.sendEvent(event);
-					}
-					// No else needed: the current provider has not been chosen - better luck next time
+					throw new IllegalStateException("Your provider doesn't have a valid PriorityFilter set. Please update your provider implementation.");
 				}
-				else
+
+				if (provider.getPriorityFilter().shouldLog(event.getPriority()))
 				{
-					// no restrictions - send the event to all registered providers
 					provider.sendEvent(event);
 				}
+				// No else needed: the provider doesn't care about logging events of the specified priority
 			}
 		}
 	}
@@ -125,20 +123,18 @@ public void endTimedEvent(@NonNull String eventName) throws IllegalStateExceptio
 				{
 					for (AnalyticsKitProvider provider : providers)
 					{
-						if (timedEvent.providersMask != 0)
+						// guard clause
+						//noinspection ConstantConditions
+						if (provider.getPriorityFilter() == null)
 						{
-							// the user has chosen to restrict the providers to which this event is sent
-							if ((provider.getType() & timedEvent.providersMask) != 0)
-							{
-								provider.endTimedEvent(timedEvent);
-							}
-							// No else needed: the current provider has not been chosen - better luck next time
+							throw new IllegalStateException("Your provider doesn't have a valid PriorityFilter set. Please update your provider implementation.");
 						}
-						else
+
+						if (provider.getPriorityFilter().shouldLog(timedEvent.getPriority()))
 						{
-							// no restrictions - send the event to all registered providers
 							provider.endTimedEvent(timedEvent);
 						}
+						// No else needed: the provider doesn't care about logging events of the specified priority
 					}
 				}
 			}

analyticskit/analyticskit.iml

@@ -29,13 +29,11 @@
 public interface AnalyticsKitProvider
 {
 	/**
-	 * Returns the type of the provider. This value should be a power of two between 2^0 and 2^30.
-	 * Please use values in the range [2^0 , 2^7] for your own custom provider implementations.
-	 * Some popular providers have already been defined as constants in {@link Providers}.
-	 * @return the specified type mask of the analytics provider.
-	 * @see Providers
+	 * Returns the filter used to restrict events by priority
+	 * @return the {@link PriorityFilter} instance the provider is using to determine if an event of a given priority should be logged
 	 */
-	int getType();
+	@NonNull
+	PriorityFilter getPriorityFilter();
 
 	/**
 	 * Sends the event using provider-specific code
@@ -48,4 +46,20 @@ public interface AnalyticsKitProvider
 	 * @param timedEvent the event which has finished
 	 */
 	void endTimedEvent(@NonNull AnalyticsEvent timedEvent);
+
+	/**
+	 * Defines the 'callback' interface providers will use to determine
+	 * how to handle events of various priorities.
+	 */
+	interface PriorityFilter
+	{
+		/**
+		 * Determines if a provider should log an event with a given priority
+		 * @param priorityLevel the priority value from an {@link AnalyticsEvent} object
+		 *                       (Generally {@link AnalyticsEvent#getPriority()})
+		 * @return {@code true} if the event should be logged by the provider.
+		 * Returns {@code false} otherwise.
+		 */
+		boolean shouldLog(int priorityLevel);
+	}
 }

analyticskit/src/main/java/com/busybusy/analyticskit_android/AnalyticsEvent.java

@@ -24,5 +24,6 @@
  */
 public interface CommonEvents
 {
-	String CONTENT_VIEW   = "Content View";
+	String CONTENT_VIEW = "Content View";
+	String ERROR        = "Error";
 }

analyticskit/src/main/java/com/busybusy/analyticskit_android/AnalyticsKit.java

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2016 Busy, LLC
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.busybusy.analyticskit_android;
+
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+/**
+ * Defines information that is needed to distribute an "Error" event to the registered analytics providers.
+ * @author John Hunt on 4/6/16.
+ */
+public class ErrorEvent extends AnalyticsEvent
+{
+	public final String ERROR_MESSAGE = "error_message";
+	public final String EXCEPTION_OBJECT = "exception_object";
+	public final String ERROR_OBJECT = "error_object";
+
+	/**
+	 * Initializes a new {@code ErrorEvent} object.
+	 */
+	public ErrorEvent()
+	{
+		super(CommonEvents.ERROR);
+	}
+
+	/**
+	 * Initializes a new {@code ErrorEvent} object.
+	 * @param eventName the name of the {@code ErrorEvent}
+	 */
+	public ErrorEvent(@NonNull String eventName)
+	{
+		super(eventName);
+	}
+
+	/**
+	 * Sets an error message on the {@code ErrorEvent}
+	 * @param errorMessage the message to set
+	 * @return the {@code ErrorEvent} instance (for builder-style convenience)
+	 */
+	public ErrorEvent setMessage(@NonNull String errorMessage)
+	{
+		putAttribute(ERROR_MESSAGE, errorMessage);
+		return this;
+	}
+
+	/**
+	 * Access the error message
+	 *
+	 * @return the error message set on this event. Returns {@code null} if the message was not set.
+	 */
+	@Nullable
+	public String message()
+	{
+		Object value = attributes != null ? attributes.get(ERROR_MESSAGE) : null;
+		return value != null ? String.valueOf(value) : null;
+	}
+
+	/**
+	 * Sets an {@code Exception} object to associate with this event
+	 * @param exception the Exception object to store
+	 * @return the {@code ErrorEvent} instance (for builder-style convenience)
+	 */
+	public ErrorEvent setException(@NonNull Exception exception)
+	{
+		putAttribute(EXCEPTION_OBJECT, exception);
+		return this;
+	}
+
+	/**
+	 * Access the {@link Exception} object
+	 *
+	 * @return the {@code Exception} set on this event. Returns {@code null} if the exception was not set.
+	 */
+	@Nullable
+	public Exception exception()
+	{
+		Object value = attributes != null ? attributes.get(EXCEPTION_OBJECT) : null;
+		return value != null ? (Exception) value : null;
+	}
+
+	/**
+	 * Sets an {@code Error} object to associate with this event
+	 * @param error the Error object to store
+	 * @return the {@code ErrorEvent} instance (for builder-style convenience)
+	 */
+	public ErrorEvent setError(@NonNull Error error)
+	{
+		putAttribute(ERROR_OBJECT, error);
+		return this;
+	}
+
+	/**
+	 * Access the {@link Error} object
+	 *
+	 * @return the {@code Error} set on this event. Returns {@code null} if the error was not set.
+	 */
+	@Nullable
+	public Error error()
+	{
+		Object value = attributes != null ? attributes.get(ERROR_OBJECT) : null;
+		return value != null ? (Error) value : null;
+	}
+}