Add Options#putContext method (#595)

Ref: LIB-634

Author: fathyb

analytics/src/main/java/com/segment/analytics/Analytics.java

@@ -781,7 +781,14 @@ private void waitForAdvertisingId() {
   void fillAndEnqueue(BasePayload.Builder<?, ?> builder, Options options) {
     waitForAdvertisingId();
 
-    AnalyticsContext contextCopy = analyticsContext.unmodifiableCopy();
+    AnalyticsContext contextCopy = new AnalyticsContext(analyticsContext);
+
+    for (Map.Entry<String, Object> pair : options.context().entrySet()) {
+      contextCopy.put(pair.getKey(), pair.getValue());
+    }
+
+    contextCopy = contextCopy.unmodifiableCopy();
+
     builder.context(contextCopy);
     builder.anonymousId(contextCopy.traits().anonymousId());
     builder.integrations(options.integrations());

analytics/src/main/java/com/segment/analytics/Options.java

@@ -41,9 +41,11 @@ public class Options {
   public static final String ALL_INTEGRATIONS_KEY = "All";
 
   private final Map<String, Object> integrations; // passed in by the user
+  private final Map<String, Object> context;
 
   public Options() {
     integrations = new ConcurrentHashMap<>();
+    context = new ConcurrentHashMap<>();
   }
 
   /**
@@ -114,8 +116,26 @@ public Options setIntegrationOptions(
     return this;
   }
 
+  /**
+   * Attach some additional context information. Unlike with {@link
+   * com.segment.analytics.Analytics#getAnalyticsContext()}, this only has effect for this call.
+   *
+   * @param key The key of the extra context data
+   * @param value The value of the extra context data
+   * @return This options object for chaining
+   */
+  public Options putContext(String key, Object value) {
+    context.put(key, value);
+    return this;
+  }
+
   /** Returns a copy of settings for integrations. */
   public Map<String, Object> integrations() {
     return new LinkedHashMap<>(integrations);
   }
+
+  /** Returns a copy of the context. */
+  public Map<String, Object> context() {
+    return new LinkedHashMap<>(context);
+  }
 }

analytics/src/test/java/com/segment/analytics/AnalyticsTest.java

@@ -348,6 +348,21 @@ public void optionsDisableIntegrations() {
     verifyNoMoreInteractions(integration);
   }
 
+  @Test
+  public void optionsCustomContext() {
+    analytics.track("foo", null, new Options().putContext("from_tests", true));
+
+    verify(integration)
+        .track(
+            argThat(
+                new NoDescriptionMatcher<TrackPayload>() {
+                  @Override
+                  protected boolean matchesSafely(TrackPayload payload) {
+                    return payload.context().get("from_tests") == Boolean.TRUE;
+                  }
+                }));
+  }
+
   @Test
   public void optOutDisablesEvents() throws IOException {
     analytics.optOut(true);

analytics/src/test/java/com/segment/analytics/OptionsTest.java

@@ -79,4 +79,23 @@ public void setIntegration() throws Exception {
                     new ImmutableMap.Builder<String, Object>().put("appId", "bar").build())
                 .build());
   }
+
+  @Test
+  public void setOptions() {
+    options.putContext("foo", "bar");
+    options.putContext(
+        "library",
+        new ImmutableMap.Builder<String, Object>().put("name", "analytics-test").build());
+
+    assertThat(options.context())
+        .isEqualTo(
+            new ImmutableMap.Builder<String, Object>()
+                .put("foo", "bar")
+                .put(
+                    "library",
+                    new ImmutableMap.Builder<String, Object>()
+                        .put("name", "analytics-test")
+                        .build())
+                .build());
+  }
 }