posthog-js 1.45.0 → 1.45.1

package/dist/module.d.ts

@@ -417,7 +417,7 @@ declare class PostHogPersistence {
     expire_days: number | undefined;
     default_expiry: number | undefined;
     cross_subdomain: boolean | undefined;
-    user_state: 'anonymous' | 'identified' | undefined;
+    user_state: 'anonymous' | 'identified';
     constructor(config: PostHogConfig);
     properties(): Properties;
     load(): void;
@@ -453,7 +453,7 @@ declare class PostHogPersistence {
     set_secure(secure: boolean): void;
     set_event_timer(event_name: string, timestamp: number): void;
     remove_event_timer(event_name: string): number;
-    get_user_state(): 'anonymous' | 'identified' | undefined;
+    get_user_state(): 'anonymous' | 'identified';
     set_user_state(state: 'anonymous' | 'identified'): void;
 }
 
@@ -1132,7 +1132,7 @@ declare class PostHog {
     /**
      * Identify a user with a unique ID instead of a PostHog
      * randomly generated distinct_id. If the method is never called,
-     * then unique visitors will be identified by a UUID generated
+     * then unique visitors will be identified by a UUID that is generated
      * the first time they visit the site.
      *
      * If user properties are passed, they are also sent to posthog.
@@ -1146,21 +1146,30 @@ declare class PostHog {
      * ### Notes:
      *
      * You can call this function to overwrite a previously set
-     * unique ID for the current user. PostHog cannot translate
-     * between IDs at this time, so when you change a user's ID
-     * they will appear to be a new user.
-     *
-     * When used alone, posthog.identify will change the user's
-     * distinct_id to the unique ID provided. When used in tandem
-     * with posthog.alias, it will allow you to identify based on
-     * unique ID and map that back to the original, anonymous
-     * distinct_id given to the user upon her first arrival to your
-     * site (thus connecting anonymous pre-signup activity to
-     * post-signup activity). Though the two work together, do not
-     * call identify() at the same time as alias(). Calling the two
-     * at the same time can cause a race condition, so it is best
-     * practice to call identify on the original, anonymous ID
-     * right after you've aliased it.
+     * unique ID for the current user.
+     *
+     * If the user has been identified ($user_state in persistence is set to 'identified'),
+     * then capture of $identify is skipped to avoid merging users. For example,
+     * if your system allows an admin user to impersonate another user.
+     *
+     * Then a single browser instance can have:
+     *
+     *  `identify('a') -> capture(1) -> identify('b') -> capture(2)`
+     *
+     * and capture 1 and capture 2 will have the correct distinct_id.
+     * but users a and b will NOT be merged in posthog.
+     *
+     * However, if reset is called then:
+     *
+     *  `identify('a') -> capture(1) -> reset() -> capture(2) -> identify('b') -> capture(3)`
+     *
+     * users a and b are not merged.
+     * Capture 1 is associated with user a.
+     * A new distinct id is generated for capture 2.
+     * which is merged with user b.
+     * So, capture 2 and 3 are associated with user b.
+     *
+     * If you want to merge two identified users, you can call posthog.alias
      *
      * @param {String} [new_distinct_id] A string that uniquely identifies a user. If not provided, the distinct_id currently in the persistent store (cookie or localStorage) will be used.
      * @param {Object} [userPropertiesToSet] Optional: An associative array of properties to store about the user

package/dist/module.js

@@ -921,7 +921,7 @@ var LZString = {
   }
 };
 
-var version = "1.45.0";
+var version = "1.45.1";
 
 // e.g.     Config.DEBUG = Config.DEBUG || instance.get_config('debug')
 
@@ -3585,7 +3585,7 @@ var PostHogPersistence = /*#__PURE__*/function () {
       this.storage = cookieStore;
     }
 
-    this.user_state = undefined;
+    this.user_state = 'anonymous';
     this.load();
     this.update_config(config);
     this.save();
@@ -3834,7 +3834,7 @@ var PostHogPersistence = /*#__PURE__*/function () {
   }, {
     key: "get_user_state",
     value: function get_user_state() {
-      return this.props[USER_STATE];
+      return this.props[USER_STATE] || 'anonymous';
     }
   }, {
     key: "set_user_state",
@@ -7390,7 +7390,7 @@ var PostHog = /*#__PURE__*/function () {
     /**
      * Identify a user with a unique ID instead of a PostHog
      * randomly generated distinct_id. If the method is never called,
-     * then unique visitors will be identified by a UUID generated
+     * then unique visitors will be identified by a UUID that is generated
      * the first time they visit the site.
      *
      * If user properties are passed, they are also sent to posthog.
@@ -7404,21 +7404,30 @@ var PostHog = /*#__PURE__*/function () {
      * ### Notes:
      *
      * You can call this function to overwrite a previously set
-     * unique ID for the current user. PostHog cannot translate
-     * between IDs at this time, so when you change a user's ID
-     * they will appear to be a new user.
-     *
-     * When used alone, posthog.identify will change the user's
-     * distinct_id to the unique ID provided. When used in tandem
-     * with posthog.alias, it will allow you to identify based on
-     * unique ID and map that back to the original, anonymous
-     * distinct_id given to the user upon her first arrival to your
-     * site (thus connecting anonymous pre-signup activity to
-     * post-signup activity). Though the two work together, do not
-     * call identify() at the same time as alias(). Calling the two
-     * at the same time can cause a race condition, so it is best
-     * practice to call identify on the original, anonymous ID
-     * right after you've aliased it.
+     * unique ID for the current user.
+     *
+     * If the user has been identified ($user_state in persistence is set to 'identified'),
+     * then capture of $identify is skipped to avoid merging users. For example,
+     * if your system allows an admin user to impersonate another user.
+     *
+     * Then a single browser instance can have:
+     *
+     *  `identify('a') -> capture(1) -> identify('b') -> capture(2)`
+     *
+     * and capture 1 and capture 2 will have the correct distinct_id.
+     * but users a and b will NOT be merged in posthog.
+     *
+     * However, if reset is called then:
+     *
+     *  `identify('a') -> capture(1) -> reset() -> capture(2) -> identify('b') -> capture(3)`
+     *
+     * users a and b are not merged.
+     * Capture 1 is associated with user a.
+     * A new distinct id is generated for capture 2.
+     * which is merged with user b.
+     * So, capture 2 and 3 are associated with user b.
+     *
+     * If you want to merge two identified users, you can call posthog.alias
      *
      * @param {String} [new_distinct_id] A string that uniquely identifies a user. If not provided, the distinct_id currently in the persistent store (cookie or localStorage) will be used.
      * @param {Object} [userPropertiesToSet] Optional: An associative array of properties to store about the user
@@ -7449,8 +7458,7 @@ var PostHog = /*#__PURE__*/function () {
           $had_persisted_distinct_id: true,
           $device_id: device_id
         }, '');
-      } // identify only changes the distinct id if it doesn't match either the existing or the alias;
-      // if it's new, blow away the alias as well.
+      } // if the previous distinct id had an alias stored, then we clear it
 
 
       if (new_distinct_id !== previous_distinct_id && new_distinct_id !== this.get_property(ALIAS_ID_KEY)) {
@@ -7460,11 +7468,10 @@ var PostHog = /*#__PURE__*/function () {
         });
       }
 
-      var deviceIdMarksForIdentify = !this.get_property('$device_id');
       var isKnownAnonymous = this.persistence.get_user_state() === 'anonymous'; // send an $identify event any time the distinct_id is changing and the old ID is an anoymous ID
       // - logic on the server will determine whether or not to do anything with it.
 
-      if (new_distinct_id !== previous_distinct_id && (isKnownAnonymous || deviceIdMarksForIdentify)) {
+      if (new_distinct_id !== previous_distinct_id && isKnownAnonymous) {
         this.persistence.set_user_state('identified');
         this.capture('$identify', {
           distinct_id: new_distinct_id,