@microsoft/power-apps-cli 0.5.3 → 0.5.4

package/node_modules/@microsoft/1ds-properties-js/README.md

@@ -0,0 +1,193 @@
+---
+ArtifactType: npm package.
+Documentation: https://eng.ms/docs/products/geneva/collect/instrument/1ds/javascriptsdk/getting-started
+Language: typescript
+Platform: various
+Stackoverflow: N/A
+Tags: 1DSJSSDK
+ms.reviewedAt: 02/21/2019
+ms.reviewedBy: ramthi
+---
+# Microsoft 1DS Web SDK Properties Plugin
+
+## Description
+1DS Web SDK Properties Plugin is used to enhance telemetry events, adding following properties:
+
+### Part A properties
+
+|  Property   | Description
+|-------------|------------------
+|  ver|major.minor where major and minor are decimal numbers. Indicates the major and minor version of the envelope. Major version is only incremented for breaking changes. Minor version changes indicate additive changes.
+
+### Part A Extensions
+
+#### [sdk](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/sdk.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  ver|SDK version (major.minor.build.revision).
+|  seq|ID incremented for each event.
+|  installId|ID created on first-time SDK initialization.
+
+
+#### [os](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/os.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  name|Operating system name.
+|  ver|Semantic: major.minor where major and minor are decimal numbers. Indicates the major and minor version of the operating system.
+
+#### [web](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/web.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  domain|Domain of the page.
+|  browser|Web browser name.
+|  browserVersion|Web browser version.
+|  screenRes|Screen resolution.
+|  userConsent| From v4.3.0 we now always write this as `false` as the value is now fully deprecated. ~~Describes whether the user has given consent for Cookies.~~
+|  consentDetails|User consent details string.
+
+#### [intweb](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/intWeb.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  msfpc|Anonymous visitor Id in hosting domain.
+|  anid|ANON - MSA Anonymous ID.
+|  serviceName|Service name.
+
+#### [utc](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/utc.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  popSample|The effective sample rate for this event at the time it was generated by a client (either the default value specified in the event definition, the system default or a dynamic override from the Settings Service). The valid range is from a minimum value of one out of every 100 million devices which is "0.000001", all the way up to all devices which is "100". If this field does not exist then you should assume its value is 100. 
+|  eventFlags|Event flags. (https://osgwiki.com/wiki/CommonSchema/flags)
+
+#### [loc](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/loc.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  tz|Time zone on the device (ISO 8601).
+
+#### [user](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/user.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  localId|The userId as known by telemetry SDK library client-side. Check the wiki on User ID for more detailed information. The format of this string is that it starts with a CSI (prefix and a colon) and then a value. The prefix must be one of the valid [user prefixes..](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/Types/UserId.md&_a=preview)
+|  locale|Language and region (IETF language tag).
+
+#### [device](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/device.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  model|The device model.
+|  make|The device make.
+|  deviceClass|The device class.
+|  localId|This is the deviceId as known by the client. A namespace prefix has been added; in 2.0 there was no prefix since this was always the SQM ID. In 2.1 there is always a prefix to indicate which type of device ID is it. The format of this string is that it starts with a CSI (prefix and a colon) and then a value. The prefix must be one of the valid [device prefixes](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/Types/DeviceId.md&_a=preview).
+
+
+#### [app](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/app.md&_a=preview)
+
+|  Property   | Description
+|-------------|------------------
+|  id|Unique identifier of the client application currently loaded in the process producing the event; used to group events together and understand usage pattern, errors by application.
+|  ver|App version. The version number of the application specified in ClientAppId. Used to understand errors by Version, Usage by Version across an App.
+|  name|App name if specified by the app.
+|  sesId|Identifier to mark session. Unless overriden, a session cookie will be used to set this value based on 30 min inactivity.
+|  locale|App locale (IETF tag, set by app on some platforms).
+|  env|The application environment.
+|  expId|The application experiment Id.
+
+#### [dt](https://msazure.visualstudio.com/DefaultCollection/One/_git/CommonSchema?path=/v4.0/PartA/dt.md&_a=preview)
+
+Only sent when the `enableDistributedTracing` configuration value is `true`, Since v3.2.3
+
+|  Property   | Description
+|-------------|------------------
+| traceId | A unique identifier for a trace. All spans from the same trace share the same traceId. Must be read from incoming headers or generated according to the [W3C TraceContext specification](https://www.w3.org/TR/trace-context/#trace-id), in a hex representation of 16-byte array. A.k.a. trace-id, TraceID or Distributed TraceID
+| spanId | Self-generated 8-bytes identifier of the incoming request. Must be a hex representation of 8-byte array.
+| traceFlags | An integer representation of the [W3C TraceContext trace-flags.](https://www.w3.org/TR/trace-context/#trace-flags)
+
+## npm
+
+Packages available [here](https://msazure.visualstudio.com/One/_artifacts/feed/1ds-sdk-js/Npm/%40microsoft%2F1ds-properties-js/overview/4.3.9).
+
+## Basic Usage
+
+### Setup
+
+```js
+import { AppInsightsCore, IExtendedConfiguration } from '@microsoft/1ds-core-js';
+import { PropertiesPlugin, IPropertyConfiguration } from '@microsoft/1ds-properties-js';
+import { PostChannel } from "@microsoft/1ds-post-js";
+```
+
+```js
+var appInsightsCore: AppInsightsCore = new AppInsightsCore();
+var propertiesPlugin: PropertiesPlugin = new PropertiesPlugin();
+var postChannel: PostChannel = new PostChannel(); 
+
+var coreConfig: IExtendedConfiguration = {
+      instrumentationKey: "YOUR_TENANT_KEY",
+      extensions: [
+        propertiesPlugin,
+        postChannel
+      ]
+};
+var propertiesPluginConfig: IPropertyConfiguration = {
+    userAgent: "Custom User Agent"
+};
+coreConfig.extensionConfig[propertiesPlugin.identifier] = propertiesPluginConfig;
+//Initialize SDK
+appInsightsCore.initialize(coreConfig, []);
+
+// Update part A properties for all events
+propertiesPlugin.getPropertiesContext().app.name = "Test App";
+propertiesPlugin.getPropertiesContext().cloud.role = "Test Cloud Role";
+
+```
+
+## Configuration
+
+
+### [IPropertyConfiguration](https://msazure.visualstudio.com/One/_git/1DS.JavaScript?path=/docs/webSdk/typedoc/ext/properties/interfaces/IPropertyConfiguration.md)
+
+|  Config   | Description | Type
+|----------------|----------------------------------------|----
+|  populateBrowserInfo     |Flag to allow client side population of browser information in web extension.| boolean
+|  populateOperatingSystemInfo     |Flag to allow client side population of os extension.| boolean
+|  userAgent     |A string that contains the user agent parsed for auto collection in case the userAgent can't be obtained from the DOM.| string
+|  userConsentCookieName     |Names the cookie used by your site to track user consent. Default is "MSCC".| string
+|  ~~userConsented~~     | From v4.3.0 this field is no longer used and is always written as false. ~~Used to manually set the value of the "userConsent" field.~~| boolean
+|  sessionRenewalMs     |A session is logged if the user is inactive for this time in milliseconds.Default 30 mins.| number
+|  sessionExpirationMs     |A session is logged if it has continued for this time in milliseconds.Default 24h.| number
+|  sessionAsGuid     | Use a guid value to identify the automatic session rather than the 6 digit value, you may also define the Guid Style to use. Defaults is false (no guid) and when true the Guid format is GuildStyle.Digits "00000000-0000-0000-0000-000000000000". | boolean or GuildStyle
+|  cookieDomain     | Override the global instance cookie domain, It is recommended to set this as part of the primary cookieCfg rather than specifically on the properties configuration to ensure that all cookies are allocated to the same domain. | string
+|  serviceName     |Field to add the name of services or SDKs in the events.| string
+|  env     |Environment is captured from meta tag. This is used to override the value or bypass defining meta tags.| string
+|  expId     |Experiment id is captured from the experiment cookie. This is used to override the value or bypass defining meta tags.| string
+|  hashIdentifiers     |Hashes the identifiable Part A fields  https://osgwiki.com/wiki/CommonSchema/flags, ext.user.localId and ext.device.localId need to be hashed if being sent and using "d:" prefix when this setting is enabled | bool
+|  dropIdentifiers     |Removes the identifiable Part A fields  https://osgwiki.com/wiki/CommonSchema/flags, ext.user.localId and ext.device.localId need use "r:" prefix when if being sent and this setting is enabled | bool
+|  callback     |Callbacks configuration. | IValueCallback
+| enableDistributedTracing<br /><sub>(Since v3.2.3)</sub> |  [Optional] Enable adding the distributed tracing values to the envelope (ext.dt), defaults to false for v3.2.x for backward compatibility this will change in a future release  | boolean
+| gpcDataSharingOptIn<br/><sub>(Since v3.2.12 and 4.0.2)</sub> | [Optional] A flag that indicates whether the user has explicitly opted in (CCPA) to data Sharing. This value has 3 possible states<br/> - Not specified - Do not add, indirectly implies that they have opted in by default<br/> - `true` - The user has explicitly opted in to allow DataSharing<br/>- `false` - The user has explicitly opted out to allow DataSharing<br/>When specified (`true`/`false`) this will add the `GPC_DataSharingOptIn` property to the `ext.web.consentDetails` sent with every event. If you also have specified a `callback.userConsentDetails` this value will be added to the returned and validated `userConsentDetails`.<br/>This value may be changed after initialization by `oneDs.getPropertyManager().getPropertiesContext().web.gpcDataSharingOptIn = true;` The values can be `true` / `false` or `null`, do NOT delete the property or set to `undefined.`<br/>With version 4.x and the dynamic configuration changes you can also just update the config `oneDs.core.config.extensionConfig.SystemPropertiesCollector.gpcDataSharingOptIn = true`, the change will take effect on the next JavaScript execution cycle (all dynamic configuration change notifications occur via a setTimeout with 0ms so all changes are batched together), once the change notification is processed the value of `oneDs.getPropertyManager().getPropertyContext().web.gpcDataSharingOptIn` is also changed. | boolean or null
+
+### IValueCallback 
+
+|  Config   | Description | Type
+|----------------|----------------------------------------|----
+|  userConsentDetails     |Function to configure user consent details in web extension. | Function
+
+## Sample App
+
+[React sample App](https://msazure.visualstudio.com/One/_git/1DS.JavaScript?path=/examples/ReactSample/README.md).
+
+[React Native sample App](https://msazure.visualstudio.com/One/_git/1DS.JavaScript.SampleApps.ReactNative?path=%2FREADME.md&version=GBmaster&_a=preview).
+
+## Learn More
+
+You can learn more in [1DS First party getting started](https://eng.ms/docs/products/geneva/collect/instrument/1ds/javascriptsdk/getting-started).
+
+## API documentation
+
+[Typedoc generated API docs](https://msazure.visualstudio.com/One/_git/1DS.JavaScript?path=/docs/webSdk/typedoc/ext/properties/README.md&anchor=api-documentation)