Skip to content

Adding a note about "initialized" event and track() callback #7024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 11, 2024

Conversation

prigiattiperrut
Copy link
Contributor

Proposed changes

  1. Added clarification on detecting when Analytics.js has loaded:
  • Instead of relying on the ready() method, users can listen for the initialize event (window.analytics.initialized). This event returns true even when a destination is blocked, providing a more reliable way to detect library loading.
  1. Updated function behavior after a 300 ms timeout:
  • Clarified that the function, which runs after a 300 ms delay to give the browser time to make outbound requests, may not execute if one of the device-mode libraries is blocked from loading.

Merge timing

ASAP once approved

@forstisabella forstisabella self-requested a review September 11, 2024 13:24
@forstisabella forstisabella merged commit 66f71a5 into develop Sep 11, 2024
3 of 4 checks passed
@forstisabella forstisabella deleted the prigiattiperrut-patch-5 branch September 11, 2024 13:24
Copy link
Contributor

Thank you for your contribution! Your pull request is merged, but may take a day or two to appear on the site.

@@ -362,7 +362,7 @@ analytics.identify("hello world")

The `ready` method lets you pass in a method that gets called after Analytics.js finishes initializing and after all enabled device-mode destinations load. It's like [jQuery's `ready` method](https://api.jquery.com/ready/){:target="_blank"}, except for Destinations. Because it doesn't fire until all enabled device-mode destinations are loaded, it can't be used to change configuration options for downstream SDKs. That can only be done if the SDK is loaded natively.

The `ready` method isn't invoked if any Destination throws an error (for example, for an expired API key, incorrect settings configuration, or when a Destination is blocked by the browser) during initialization.
The `ready` method isn't invoked if any Destination throws an error (for example, for an expired API key, incorrect settings configuration, or when a Destination is blocked by the browser) during initialization. If you're looking to detect when Analytics.js has loaded, instead of using the `ready` method, you can listen for the `initialize` event to be emitted (`window.analytics.initialized`). This event returns `true` even when a destination is blocked.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm confused by this line. Generally when the terms "listen", "emit" and "event" are used, it's in reference to a pubsub system. Such a system would be ideal. Something like...

window.analytics.on('initialized', function(event, properties, options) {
  console.log(event, properties, options)
});

However, I'm not seeing any way of subscribing here. To date, window.analytics.initialized is a single boolean value. The only way I can see to "listen" to it would be to set up an interval that poles for the value to change. This is do-able (albeit inelegant, IMO).

If I'm correct, and there is no way of subscribing to changes in window.analytics.initialized, I'd strongly suggest updating this doc for clarity. And if there is a way of subscribing, I'd suggest linking to that documentation here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @JohnMealy23, thanks for your note! I've created a new PR to address the adjustment:
https://github.com/segmentio/segment-docs/pull/7036/files

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants