Merge branch 'master' into niall/amplitude_group_call

Author: sanscontext

src/connections/destinations/catalog/adobe-analytics/index.md

@@ -66,7 +66,7 @@ Device-mode web data is sent using Analytics.js, with Analytics.js either servin
 
 Our Adobe Analytics device-mode destination code is open sourced on Github. Feel free to check it out:
 [iOS](https://github.com/segment-integrations/analytics-ios-integration-adobe-analytics),
-[Android](hhttps://github.com/segment-integrations/analytics-android-integration-adobe-analytics) and
+[Android](https://github.com/segment-integrations/analytics-android-integration-adobe-analytics) and
 [JS](https://github.com/segmentio/analytics.js-integrations/tree/master/integrations/adobe-analytics).
 
 ### Initialization

src/connections/destinations/catalog/algolia-insights/index.md

@@ -71,7 +71,7 @@ Algolia supports the following six events from Segment's [Ecommerce Spec](https:
 analytics.track('Product List Viewed', {
     products: [{
         objectID: "hit objectID",
-        position: "hit position on index",
+        position: hitPositionOnIndex,  // number
         index: "my-index-name",
         queryID: "Algolia queryID" // required only for Click Analytics,
     }]
@@ -86,15 +86,15 @@ analytics.track('Product List Filtered', {
 
 analytics.track('Product Viewed', {
     objectID: "hit objectID",
-    position: "hit position on index",
+    position: hitPositionOnIndex,  // number
     index: "my-index-name",
     queryID: "Algolia queryID" // required only for Click Analytics,
 })
 
 
 analytics.track('Product Clicked', {
     objectID: "hit objectID",
-    position: "hit position on index",
+    position: hitPositionOnIndex,  // number
     index: "my-index-name",
     queryID: "Algolia queryID" // required only for Click Analytics,
 })

src/connections/destinations/catalog/taplytics/index.md

@@ -11,21 +11,21 @@ Once the Segment library is integrated with your app, add your API key and selec
 Follow the below steps for destination
 
 ### iOS
-To get started with Taplytics on iOS, first integrate your app with the Taplytics [iOS](/docs/connections/sources/catalog/libraries/mobile/ios) library. To get the API key, [login](https://taplytics.com/) to your account, select the App on the top left then click into the Settings menu on the left side. If you want to set up Push Notifications click on the Push Notification tab in their UI and [follow the instructions](https://taplytics.com/docs/guides/push-notifications/apple-push-certificates). Finally, you want to ensure you have configured your app delegate to [enable push notifications](/docs/connections/sources/catalog/libraries/mobile/ios/#how-do-i-use-push-notifications).
+To get started with Taplytics on iOS, first integrate your app with the Taplytics [iOS](/docs/connections/sources/catalog/libraries/mobile/ios) library. To get the API key, [login](https://taplytics.com/) to your account, select the App on the top left then click into the Settings menu on the left side. If you want to set up Push Notifications click on the Push Notification tab in their UI and [follow the instructions](https://docs.taplytics.com/docs/guides-push-notifications). Finally, you want to ensure you have configured your app delegate to [enable push notifications](/docs/connections/sources/catalog/libraries/mobile/ios/#how-do-i-use-push-notifications).
 
-If you want to set up deep linking, just follow [this section of their docs](https://taplytics.com/docs/ios-sdk/getting-started#app-linking)!
+If you want to set up deep linking, just follow [this section of their docs](https://support.taplytics.com/hc/en-us/articles/360004176632-Deep-Linking-Guide-)!
 
-For more information about setting up Taplytics on iOS, see their [docs](https://taplytics.com/docs/ios-sdk/getting-started)
+For more information about setting up Taplytics on iOS, see their [docs](https://docs.taplytics.com/docs/ios-getting-started)
 
 
 ### Android
 To get up and running with Taplytics on Android, there a couple of steps we will walk you through. You first want to ensure that you've integrated your mobile app with our [Android](/docs/connections/sources/catalog/libraries/mobile/android) library.
 
-To enable its full functionality (like Push Notifications, Deep linking), there are a couple of extra steps that you have to take care of in your Android app. [This document explains how to set up Push Notifications](https://taplytics.com/docs/android-sdk/push-notifications) and [ths one explains how to set up deep linking](https://taplytics.com/docs/android-sdk/getting-started#device-pairing).
+To enable its full functionality (like Push Notifications, Deep linking), there are a couple of extra steps that you have to take care of in your Android app. [This document explains how to set up Push Notifications](https://docs.taplytics.com/docs/guides-push-notifications) and [ths one explains how to set up deep linking](https://support.taplytics.com/hc/en-us/articles/360004176632-Deep-Linking-Guide-).
 
 
 ## Identify
-Use [Identify](/docs/connections/sources/catalog/libraries/mobile/ios/#identify) to track user specific attributes. It equivalent to tracking [user attributes](https://taplytics.com/docs/guides/user-attributes-setup) on Taplytics. Taplytics supports traits supported by Segment as well as custom traits. If you set traits.id, we set that as the Unique ID for that user.
+Use [Identify](/docs/connections/sources/catalog/libraries/mobile/ios/#identify) to track user specific attributes. It equivalent to tracking [user attributes](https://docs.taplytics.com/docs/guides-user-insights) on Taplytics. Taplytics supports traits supported by Segment as well as custom traits. If you set traits.id, we set that as the Unique ID for that user.
 
 ## Track
 Use [track](/docs/connections/sources/catalog/libraries/mobile/ios/#track) to track events and user behaviour in your app.

src/connections/functions/destination-functions.md

@@ -86,11 +86,12 @@ To change which type of event the handler listens to, you can rename it to the n
 
 A function's execution is considered successful if it finishes without any errors. You can also `throw` an error to indicate a failure on purpose. You can use these errors to validate event data before processing it, to ensure your function works as expected.
 
-There are three pre-defined error types that you can `throw` to indicate that the function ran as expected, but that data could not be delivered:
+You can `throw` the following pre-defined error types to indicate that the function ran as expected, but that data could not be delivered:
 
 - `EventNotSupported`
 - `InvalidEventPayload`
 - `ValidationError`
+- `RetryError`
 
 The examples show basic uses of these error types.
 
@@ -110,6 +111,27 @@ async function onPage(event) {
 async function onAlias(event) {
   throw new EventNotSupported('Alias event is not supported')
 }
+
+async function onTrack(event) {
+  let res
+  try {
+    res = await fetch('http://example-service.com/api', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ event })
+    })
+  } catch (err) {
+    // Retry on connection error
+    throw new RetryError(err.message)
+  }
+  if (res.status >= 500 || res.status === 429) {
+    // Retry on 5xx and 429s (ratelimits)
+    throw new RetryError(`HTTP Status ${res.status}`)
+  }
+}
+
 ```
 If you do not supply a function for an event type, Segment throws an `EventNotSupported` error by default.
 
@@ -186,8 +208,9 @@ A function can throw errors, or Segment might encounter errors while invoking yo
 - **Invalid Settings** - A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/).
 - **Message Rejected** - Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
 - **Unsupported Event Type** - Your code does not implement a specific event type (`onTrack()`, etc.) or threw a `EventNotSupported` error.
+- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
 
-When these errors occur, Segment does not attempt to send that event to your destination function again.
+Segment only attempts to send the event to your destination function again if a **Retry** error occurs.
 
 ### Destination functions logs
 

src/connections/functions/source-functions.md

@@ -350,8 +350,9 @@ async function onRequest(request, settings) {
 - **Invalid Settings**: A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/).
 - **Message Rejected**: Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
 - **Unsupported Event Type**: Your code does not implement a specific event type (`onTrack()`, etc.) or threw a `EventNotSupported` error.
+- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
 
-These errors are not retried.
+Segment only attempts to run your source function again if a **Retry** error occurs.
 
 ## Managing source functions
 

src/connections/sources/catalog/libraries/mobile/ios/index.md

@@ -102,7 +102,7 @@ configuration.trackPushNotifications = YES;
 ```
 
 ### Automatic Deep Link Tracking
-Tracking deep linking will automatically track `Deep Link Clicked` and `Deep Link Opened`.
+Tracking deep linking will automatically track `Deep Link Opened`.
 
 ```objc
 SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"];

src/connections/sources/catalog/libraries/website/javascript/middleware.md

@@ -53,6 +53,9 @@ var DMW1 = function({ payload, integration, next }) {
 };
 ```
 
+> note ""
+> Currently only Device-mode Destinations are supported by Destination Middlewares 
+
 ## Adding middlewares to Analytics.js
 
 The above defined Source & Destination Middleware can be added to the Analytics.js execution chain as:

src/connections/sources/catalog/libraries/website/javascript/troubleshooting.md

@@ -112,6 +112,25 @@ console.log(JSON.stringify({ x: undefined, y: 6 }));
 // expected output: "{"y":6}"
 ```
 
+
+### Can I overwrite the context fields?
+
+Yes.  This can be useful if some of these fields contain information you don't want to collect.  
+
+For example, imagine that your website allows users to view a receipt for purchases at the URL `https://mywebsite.com/store/purchases`.  Your users click a link that redirects to that specific URL, your app sets a `receiptId` in the query string, and returns the appropriate receipt.  You also send a Track call to Segment from this page.
+
+Since this `receiptId` might contain sensitive information, you can prevent the context field `page.url` from being included in your Track call by overwriting the field in the `options` parameter, as in the example below:
+
+```js
+analytics.track("Receipt Viewed", {}, {
+    page: {
+        url: null
+    }   
+})
+```
+
+This works for any [context field](/docs/connections/spec/common/#context) that Segment automatically collects.
+
 ## Known Issues:
 
 [Review and contribute to these on Github](https://github.com/segmentio/analytics.js/issues)