@microsoft/1ds-post-js

---

ArtifactType: npm package. Documentation: https://1dsdocs.azurewebsites.net/getting-started/javascript-getting_started.html Language: typescript Platform: various Stackoverflow: N/A Tags: 1DSJSSDK ms.reviewedAt: 02/21/2019 ms.reviewedBy: ramthi

Microsoft 1DS Web SDK Post Plugin

Description

1DS Web SDK Post Channel main functionality is to send data to OneCollector using POST, currently supporting XMLHttpRequest, fetch API and XDomainRequest.

npm

Package available here.

Basic Usage

Setup

import { AppInsightsCore, IExtendedConfiguration } from '@microsoft/1ds-core-js';
import { PostChannel, IChannelConfiguration } from '@microsoft/1ds-post-js';

var appInsightsCore: AppInsightsCore = new AppInsightsCore();
var postChannel: PostChannel = new PostChannel();
var coreConfig: IExtendedConfiguration = {
      instrumentationKey: "YOUR_TENANT_KEY",
      extensions: [
        postChannel
      ],
      extensionConfig: []
};
var postChannelConfig: IChannelConfiguration = {
    eventsLimitInMem: 50
};
coreConfig.extensionConfig[postChannel.identifier] = postChannelConfig;
//Initialize SDK
appInsightsCore.initialize(coreConfig, []);

Configuration

IChannelConfiguration

| Config | Description | Type |----------------|----------------------------------------|----|----------------------------------------------------------| | eventsLimitInMem | The number of events that can be kept in memory before the SDK starts to drop events. By default, this is 10,000.|number | autoFlushEventsLimit | [Optional] If defined, once this number of events has been queued the system perform a flush() to send the queued events without waiting for the normal schedule timers. Default is undefined | number | httpXHROverride |The HTTP override that should be used to send requests, request properties and headers should be added to the request to maintain correct functionality with other plugins.|IXHROverride | overrideInstrumentationKey |Override for Instrumentation key.|string | overrideEndpointUrl |Override for Endpoint where telemetry data is sent.|string | disableTelemetry |The master off switch. Do not send any data if set to TRUE.|boolean | ignoreMc1Ms0CookieProcessing |MC1 and MSFPC cookies will not be provided. Default is false.|boolean | payloadPreprocessor |POST channel preprocessing function. Can be used to gzip the payload (and set appropriate HTTP headers) before transmission. |Function | payloadListener |POST channel function hook to listen to events being sent, called after the batched events have been committed to be sent. Also used by Remote DDV Channel to send requests. |Function | disableEventTimings | [Optional] By default additional timing metrics details are added to each event after they are sent to allow you to review how long it took to create serialized request. As not all users require this level of detail and it's now possible to get the same metrics via the IPerfManager and IPerfEvent, so you can now disabled this previous level. Default value is false to retain the previous behavior, if you are not using these metrics and performance is a concern then it is recommended to set this value to true. | boolean | valueSanitizer | [Optional] The value sanitizer to use while constructing the envelope, if not provided the default sanitizeProperty() method is called to validate and convert the fields for serialization. The path / fields names are based on the format of the envelope (serialized object) as defined via the Common Schema 4.0 specification. | IValueSanitizer | stringifyObjects | [Optional] During serialization, when an object is identified should the object serialized by true => JSON.stringify(theObject); otherwise theObject.toString(). Defaults to false. | boolean | enableCompoundKey | [Optional] Enables support for objects with compound keys which indirectly represent an object eg. event: { "somedata.embeddedvalue": 123 } where the "key" of the object contains a "." as part of it's name. Defaults to false. | boolean

IXHROverride

| Config | Description | Type |----------------|----------------------------------------|----|----------------------------------------------------------| | sendPOST |This method sends data to the specified URI using a POST request. If sync is true then the request is sent synchronously. The oncomplete function should always be called after the request is completed (either successfully or timed out or failed due to errors).|function

Payload Preprocessors

interface IPayloadData {
    urlString: string;
    data: Uint8Array | string;
    headers?: { [name: string]: string };
}

type PayloadPreprocessorFunction = (payload: IPayloadData, callback: (modifiedBuffer: IPayloadData) => void) => void;

To perform some preprocessing operation on your payload before it is sent over the wire, you can supply the POST channel config with a payloadPreprocessor function. A typical usage of it would be to gzip your payloads.

const zlib = require('zlib');
const gzipFn: PayloadPreprocessorFunction = (payload: IPayloadData, cb) => {
  zlib.gzip(payload.data, (err, dataToSend) => {
    if (err) return cb(payload); // send original payload on error
    const payloadToSend = {
      ...payload,
      headers: { ...payload.headers, 'Content-Encoding': 'gzip' };
      data: dataToSend,
    };
    cb(payloadToSend);
  });
}

IValueSanitizer Paths / Fields which are excluded

To ensure that the service can continue to accept events that are sent from the SDK, some paths and fields are explicitly blocked and are never processed via any configured valueSanitizer. These fields are blocked at the serialization level and cannot be overridden.

The path / fields names are based on the format of the envelope (serialized object) as defined via the Common Schema 4.0 specification, so the path / field names used for the IValueSanitizer are based on how the data is serialized to the service (CS 4.0 location) and not specifically the location on the event object you pass into the track methods (unless they are the same).

The currently configured set of fields include

Excluded Part A fields

• All direct top-level fields of the envelope, this includes "ver"; "name"; "time" and "iKey". see Common Schema 4.0 - Part A for all defined fields. Note: This exclusion does does not match sub-keys (objects) like "ext", "data" and "properties".
• All fields of the web extension, this includes all fields and sub keys of "ext.web" (example fields include "ext.web.browser"; "ext.web.domain"; "ext.web.consentDetails"). see Common Schema 4.0 - Part A Extension - web for the complete set of defined fields.
• All fields and paths of the metadata extension, this includes all fields and sub keys of "ext.metadata". see Common Schema 4.0 - Part A Extension - metadata for the complete set of defined fields.

API documentation

https://1dsdocs.azurewebsites.net/api/webSDK/chnl/post/3.0/f/index.html

Sample App

React sample App.

React Native sample App.

Learn More

You can learn more in 1DS First party getting started.

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

To turn off sending telemetry to Microsoft, ensure that the POST channel is not configured in the extensions. See below configuration for example:

var coreConfig: IExtendedConfiguration = {
      instrumentationKey: "YOUR_TENANT_KEY",
      extensions: [
        postChannel  // << REMOVE THIS EXTENSION TO STOP SENDING TELEMETRY TO MICROSOFT
      ],
      extensionConfig: []
};

License

MIT