Merge pull request #165 from apptentive/branch_5.2.0

Release 5.2.0

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 2018-08-23 - v5.2.0
+
+#### Improvements
+
+* Added `OnPreInteractionListener` to intercept interactions flow.
+
 # 2018-07-19 - v5.1.5
 
 #### Improvements

README.md

@@ -13,7 +13,7 @@ use your app, to talk to them at the right time, and in the right way.
 
 ##### [Release Notes](https://learn.apptentive.com/knowledge-base/android-sdk-release-notes/)
 
-##### Binary releases are hosted for Maven [here](http://search.maven.org/#artifactdetails|com.apptentive|apptentive-android|5.1.5|aar)
+##### Binary releases are hosted for Maven [here](http://search.maven.org/#artifactdetails|com.apptentive|apptentive-android|5.2.0|aar)
 
 #### Reporting Bugs
 

apptentive/src/main/java/com/apptentive/android/sdk/Apptentive.java

@@ -14,6 +14,7 @@
 import android.net.Uri;
 import android.os.Bundle;
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.text.TextUtils;
 import android.webkit.MimeTypeMap;
 
@@ -61,6 +62,8 @@
  */
 public class Apptentive {
 
+	private static OnPreInteractionListener preInteractionListener;
+
 	/**
 	 * Must be called from the {@link Application#onCreate()} method in the {@link Application} object defined in your app's manifest.
 	 * Note: application key and signature would be resolved from the AndroidManifest.xml
@@ -1163,6 +1166,8 @@ protected boolean execute(Conversation conversation) {
 
 	//endregion
 
+	//region Engagement
+
 	/**
 	 * This method takes a unique event string, stores a record of that event having been visited,
 	 * determines if there is an interaction that is able to run for this event, and then runs it. If
@@ -1315,10 +1320,32 @@ public static synchronized void engage(final Context context, final String event
 			throw new IllegalArgumentException("Event is null or empty");
 		}
 
+		// first, we check if there's an engagement callback to inject
+		final OnPreInteractionListener preInteractionListener = Apptentive.preInteractionListener; // capture variable to avoid concurrency issues
+		if (preInteractionListener != null) {
+			dispatchConversationTask(new ConversationDispatchTask(callback, DispatchQueue.mainQueue()) {
+				@Override
+				protected boolean execute(Conversation conversation) {
+					if (!canShowLocalAppInteraction(conversation, event)) {
+						return false;
+					}
+
+					boolean allowsInteraction = preInteractionListener.shouldEngageInteraction(event, customData);
+					ApptentiveLog.i("Engagement callback allows interaction for event '%s': %b", event, allowsInteraction);
+					if (!allowsInteraction) {
+						return false;
+					}
+
+					return engageLocalAppEvent(context, conversation, event, customData, extendedData); // actually engage event
+				}
+			}, StringUtils.format("engage '%s' event", event));
+			return;
+		}
+
 		dispatchConversationTask(new ConversationDispatchTask(callback, DispatchQueue.mainQueue()) {
 			@Override
 			protected boolean execute(Conversation conversation) {
-				return EngagementModule.engage(context, conversation, "local", "app", null, event, null, customData, extendedData);
+				return engageLocalAppEvent(context, conversation, event, customData, extendedData);
 			}
 		}, StringUtils.format("engage '%s' event", event));
 	}
@@ -1337,11 +1364,28 @@ public static synchronized void queryCanShowInteraction(final String event, Bool
 		dispatchConversationTask(new ConversationDispatchTask(callback, DispatchQueue.mainQueue()) {
 			@Override
 			protected boolean execute(Conversation conversation) {
-				return EngagementModule.canShowInteraction(conversation, "app", event, "local");
+				return canShowLocalAppInteraction(conversation, event);
 			}
 		}, "check if interaction can be shown");
 	}
 
+	/**
+	 * Sets an optional engagement callback.
+	 */
+	public static synchronized void setOnPreInteractionListener(@Nullable OnPreInteractionListener onPreInteractionListener) {
+		Apptentive.preInteractionListener = onPreInteractionListener;
+	}
+
+	private static boolean engageLocalAppEvent(Context context, Conversation conversation, String event, Map<String, Object> customData, ExtendedData[] extendedData) {
+		return EngagementModule.engage(context, conversation, "local", "app", null, event, null, customData, extendedData);
+	}
+
+	private static boolean canShowLocalAppInteraction(Conversation conversation, String event) {
+		return EngagementModule.canShowInteraction(conversation, "app", event, "local");
+	}
+
+	//endregion
+
 	/**
 	 * Pass in a listener. The listener will be called whenever a survey is finished.
 	 * Do not pass in an anonymous class, such as setOnSurveyFinishedListener(new OnSurveyFinishedListener() {...}).
@@ -1777,6 +1821,19 @@ public int compareTo(DateTime other) {
 		}
 	}
 
+	/**
+	 * Represents a callback which will be invoked right before an interaction is engaged. Can be used
+	 * to intercept the default engagement flow.
+	 */
+	public interface OnPreInteractionListener {
+		/**
+		 * @param event event which triggered the interaction.
+		 * @param customData optional custom data map passed to the engagement call.
+		 * @return <code>true</code> if interaction should be engaged. Otherwise, it would be cancelled.
+		 */
+		boolean shouldEngageInteraction(String event, @Nullable Map<String, Object> customData);
+	}
+
 	/**
 	 * Allows certain Apptentive API methods to execute and return a boolean result asynchronously.
 	 */

apptentive/src/main/java/com/apptentive/android/sdk/util/Constants.java

@@ -9,7 +9,7 @@
 public class Constants {
 
 	public static final int  API_VERSION = 9;
-	private static final String APPTENTIVE_SDK_VERSION = "5.1.5";
+	private static final String APPTENTIVE_SDK_VERSION = "5.2.0";
 
 	public static final int DEFAULT_CONNECT_TIMEOUT_MILLIS = 45000;
 	public static final int DEFAULT_READ_TIMEOUT_MILLIS = 45000;