nativescript-segment - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

package.json

 {
 	"name": "nativescript-segment",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"description": "Your awesome NativeScript plugin.",
@@ -5,0 +5,0 @@ "main": "segment",

README.md

@@ -1,40 +0,199 @@
-# Your Plugin Name
+# Nativescript-Segment
 
-Add your plugin badges here. See [nativescript-urlhandler](https://github.com/hypery2k/nativescript-urlhandler) for example.
+A NativeScript plugin that provides easy access to the native Segment SDKs.
+Largely based on this [repository](https://github.com/travtarr/nativescript-segment).
 
-Then describe what's the purpose of your plugin. 
+- iOS SDK [Official Repository](https://github.com/segmentio/analytics-ios)
+- Android SDK [Official Repository](https://github.com/segmentio/analytics-android)
 
-In case you develop UI plugin, this is where you can add some screenshots.
+## Installation
 
-## (Optional) Prerequisites / Requirements
+```
+tns plugin add nativescript-segment
+```
 
-Describe the prerequisites that the user need to have installed before using your plugin. See [nativescript-firebase plugin](https://github.com/eddyverbruggen/nativescript-plugin-firebase) for example.
+For access to the native SDK type definitions, specify the definitions in your *references.d.ts*
 
-## Installation
+```typescript
+/// <reference path="./node_modules/nativescript-segment/platforms/android/typings/android.d.ts" />
+/// <reference path="./node_modules/nativescript-segment/platforms/ios/typings/ios.d.ts" />
+```
 
-Describe your plugin installation steps. Ideally it would be something like:
+*Warning: Depending on your project structure, the paths shown above may be inaccurate.*
 
-```javascript
-tns plugin add <your-plugin-name>
+## Usage
+
+### Example
+All interaction with the library should be done via static function calls on the Segment import since both iOS and Android SDKs instantiate Segment as a singleton once the method configure has been successfully called.
+
+```typescript
+const config: SegmentConfig = {
+    trackLifeCycleEvents: true,
+    recordScreenViews: true
+};
+Segment.configure(SEGMENT_KEY, config); // SEGMENT_KEY being your secret key
 ```
 
-## Usage 
+```typescript
+import { Segment } from 'nativescript-segment';
 
-Describe any usage specifics for your plugin. Give examples for Android, iOS, Angular if needed. See [nativescript-drop-down](https://www.npmjs.com/package/nativescript-drop-down) for example.
-	
-	```javascript
-    Usage code snippets here
-    ```)
+public someInteraction(type: string) {
+    Segment.track(type);
+}
+```
 
+For more advanced uses, or if it is required to access the base SDK methods, you can access the SDK's shared instance
+
+```typescript
+// iOS
+Segment.ios.track('some event');
+
+// Android
+Segment.android.track('some event');
+```
+
+*Warning: accessing the SDK's methods directly potentially requires converting to native object and collection types*
+
+## Platform specifics
+
+### Android
+
+Requires the *internet* permission if not already enabled in your app.
+```xml
+<uses-permission android:name="android.permission.INTERNET"/>
+```
+
+### iOS best practice
+
+In your application's delegate:
+
+```js
+import { Segment } from 'nativescript-segment';
+
+public applicationDidFinishLaunchingWithOptions(application, launchOptions): boolean {
+    const config = {
+        setDebug: true; // set to show full debug logging by the native APIs
+    }
+    Segment.configure(key, config);
+    return true;
+}
+```
+
 ## API
 
-Describe your plugin methods and properties here. See [nativescript-feedback](https://github.com/EddyVerbruggen/nativescript-feedback) for example.
-    
+### configure
+
+```js
+const config: SegmentConfig = {
+    trackLifeCycleEvents: true,
+    recordScreenViews: true
+};
+Segment.configure('your segment write key', config);
+```
+
+**SegmentConfig** Properties (all optional)
+
 | Property | Default | Description |
 | --- | --- | --- |
-| some property | property default value | property description, default values, etc.. |
-| another property | property default value | property description, default values, etc.. |
+| trackLifeCycleEvents | true | enable or disable auto tracking life-cycle events |
+| recordScreenViews| true | enable or disable auto tracking of screen views |
+| options | | Default integration options, see **SegmentOptions** |
+| proxyUrl | null | forward all Segment calls through a proxy |
+| setLogging | false | set base *INFO* logging in Android SDK and plugin itself |
+| setDebug | false | Sets full debug logging in Android and iOS |
+| middlewaresAndroid | [] | List of middlewares for Android. Applied in the order based on the array. See [here](https://segment.com/docs/sources/mobile/android/#middlewares) for more info |
+| middlewaresIOS | [] | List of middlewares for iOS. Applied in the order based on the array. See [here](https://segment.com/docs/sources/mobile/ios/#middlewares) for more info |
+
+**SegmentOptions** Properties (all optional)
+
+| Property | Default | Description |
+| --- | --- | --- |
+| useAll | true | enables all integrations (default for Segment SDKs) |
+| excluded | [] | exclude Segment from integrating with the specified services |
+| included | [] | include Segment integration with the specified services (note: this will only take affect if **useAll** is set to *false*) |
     
+
+### identify
+
+Identify the current user.  Additional traits are supported, and custom traits are available.
+
+```js
+const traits: SegmentTraits = {
+    firstName: 'Dave',
+    email: '[e-mail]'
+};
+const customTraits: any {
+    favoriteColor: 'blue'
+};
+Segment.identify('userId', traits, customTraits);
+```
+
+**SegmentTraits** Properties (all optional)
+
+Please see [Segment's official spec](https://segment.com/docs/spec/identify/#traits) for all available traits and their descriptions.
+
+
+### track
+
+Track an event. 
+
+```js
+Segment.track('Some event');
+
+const properties = {
+    productName: 'Bread',
+    revenue: 4
+};
+Segment.track('Product Purchased', properties);
+```
+
+Please see [Segment's official spec](https://segment.com/docs/spec/track/#properties) for details on properties to add to *track* calls.
+
+### screen
+
+Manually record a screen view by name and optional category.  Category is a default option for Android, but for iOS it will concatenate *category* and *name* into the same `screen`.
+
+```js
+Segment.screen('signup', 'verify password');
+```
+
+Please see [Segment's official spec](https://segment.com/docs/spec/screen/#properties) for details on *screen* calls.
+
+### group
+
+Associate current user with a group.  A user can belong to multiple groups.
+
+```js
+Segment.group("0e8c78ea9d97a7b8185e8632", {
+  name: "Initech", 
+  industry: "Technology",
+  employees: 329, 
+  plan: "enterprise", 
+  "total billed": 830
+});
+```
+
+Please see [Segment's official spec](https://segment.com/docs/spec/group/#properties) for details on *group* calls.
+
+
+### alias
+
+*alias* is how you associate one identity with another.
+
+```js
+Segment.alias(newId);
+```
+
+Please see [Segment's official spec](https://segment.com/docs/spec/alias) for details on *alias* calls.
+
+### optout
+
+Disables or enables all analytics, remains set throughout app restarts.
+
+```js
+Segment.optOut(true);
+```
+
 ## License
 
 Apache License Version 2.0, January 2004

segment.android.d.ts

@@ -7,9 +7,9 @@ import { Common, SegmentConfig, SegmentTraits, SegmentOptions } from './segment.common';
     readonly android: com.segment.analytics.Analytics;
-    configure(key: string, configOptions?: SegmentConfig): void;
-    identify(id: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
-    track(event: string, properties?: any, options?: SegmentOptions): void;
-    screen(name: string, category?: string, properties?: any, options?: SegmentOptions): void;
-    group(groupId: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
-    alias(newId: string, options?: SegmentOptions): void;
-    optOut(optOut: boolean): void;
+    static configure(key: string, configOptions?: SegmentConfig): void;
+    static identify(id: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
+    static track(event: string, properties?: any, options?: SegmentOptions): void;
+    static screen(name: string, category?: string, properties?: any, options?: SegmentOptions): void;
+    static group(groupId: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
+    static alias(newId: string, options?: SegmentOptions): void;
+    static optOut(optOut: boolean): void;
 }

segment.android.js

@@ -18,3 +18,3 @@ "use strict";
     });
-    Segment.prototype.configure = function (key, configOptions) {
+    Segment.configure = function (key, configOptions) {
         var analyticsBuilder = new Analytics.Builder(app.android.context, key);
@@ -53,9 +53,9 @@ if (configOptions !== undefined) {
     };
-    Segment.prototype.identify = function (id, traits, customTraits, options) {
+    Segment.identify = function (id, traits, customTraits, options) {
         this.android.identify(id, _convertTraits(traits, customTraits), _convertOptions(options));
     };
-    Segment.prototype.track = function (event, properties, options) {
+    Segment.track = function (event, properties, options) {
         this.android.track(event, _convertProperties(properties), _convertOptions(options));
     };
-    Segment.prototype.screen = function (name, category, properties, options) {
+    Segment.screen = function (name, category, properties, options) {
         if (!category && !name) {
@@ -67,9 +67,9 @@ _log("Both \"category\" and \"name\" parameters of the screen method cannot be null");
     };
-    Segment.prototype.group = function (groupId, traits, customTraits, options) {
+    Segment.group = function (groupId, traits, customTraits, options) {
         this.android.group(groupId, _convertTraits(traits, customTraits), _convertOptions(options));
     };
-    Segment.prototype.alias = function (newId, options) {
+    Segment.alias = function (newId, options) {
         this.android.alias(newId, _convertOptions(options));
     };
-    Segment.prototype.optOut = function (optOut) {
+    Segment.optOut = function (optOut) {
         this.android.optOut(optOut);
@@ -76,0 +76,0 @@ };

segment.ios.d.ts

@@ -6,9 +6,9 @@ import { Common, SegmentConfig, SegmentTraits, SegmentOptions } from './segment.common';
     readonly ios: SEGAnalytics;
-    configure(key: string, configOptions?: SegmentConfig): void;
-    identify(id: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
-    track(event: string, properties?: any, options?: SegmentOptions): void;
-    screen(name: string, category?: string, properties?: any, options?: SegmentOptions): void;
-    group(groupId: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
-    alias(newId: string, options?: SegmentOptions): void;
-    optOut(optOut: boolean): void;
+    static configure(key: string, configOptions?: SegmentConfig): void;
+    static identify(id: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
+    static track(event: string, properties?: any, options?: SegmentOptions): void;
+    static screen(name: string, category?: string, properties?: any, options?: SegmentOptions): void;
+    static group(groupId: string, traits?: SegmentTraits, customTraits?: any, options?: SegmentOptions): void;
+    static alias(newId: string, options?: SegmentOptions): void;
+    static optOut(optOut: boolean): void;
 }

segment.ios.js

@@ -13,3 +13,3 @@ "use strict";
     });
-    Segment.prototype.configure = function (key, configOptions) {
+    Segment.configure = function (key, configOptions) {
         var configuration = SEGAnalyticsConfiguration.configurationWithWriteKey(key);
@@ -47,9 +47,9 @@ if (configOptions !== undefined) {
     };
-    Segment.prototype.identify = function (id, traits, customTraits, options) {
+    Segment.identify = function (id, traits, customTraits, options) {
         this.ios.identifyTraitsOptions(id, _convertTraits(traits, customTraits), _convertOptions(options));
     };
-    Segment.prototype.track = function (event, properties, options) {
+    Segment.track = function (event, properties, options) {
         this.ios.trackPropertiesOptions(event, _convertProperties(properties), _convertOptions(options));
     };
-    Segment.prototype.screen = function (name, category, properties, options) {
+    Segment.screen = function (name, category, properties, options) {
         if (!category && !name) {
@@ -65,9 +65,9 @@ _log("Both \"category\" and \"name\" parameters of the screen method cannot be null");
     };
-    Segment.prototype.group = function (groupId, traits, customTraits, options) {
+    Segment.group = function (groupId, traits, customTraits, options) {
         this.ios.groupTraitsOptions(groupId, _convertTraits(traits, customTraits), _convertOptions(options));
     };
-    Segment.prototype.alias = function (newId, options) {
+    Segment.alias = function (newId, options) {
         this.ios.aliasOptions(newId, _convertOptions(options));
     };
-    Segment.prototype.optOut = function (optOut) {
+    Segment.optOut = function (optOut) {
         if (optOut) {
@@ -74,0 +74,0 @@ this.ios.disable();

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

68455

increased by6.66%

Number of lines in readme file

200

increased by387.8%

No dependency changes