16 |
17 |
18 | 
19 |
20 |
21 | 
22 |
23 |
24 | 
25 |
26 |
27 |
28 | Version {{app-version hideSha=true}}
29 | {{/if}} 30 | {{/docs-hero}} 31 | 32 |
33 |
59 | 60 | {{parent-interactivity}} 61 |
--------------------------------------------------------------------------------
/tests/unit/mixins/component-interactivity-test.js:
--------------------------------------------------------------------------------
1 | import { module } from 'qunit';
2 | import { setupTest } from 'ember-qunit';
3 | import test from 'ember-sinon-qunit/test-support/test';
4 | import RSVP from 'rsvp';
5 | import EmberObject from '@ember/object';
6 | import Service from '@ember/service';
7 | import { setOwner } from '@ember/application';
8 | import { sendEvent as send } from '@ember/object/events';
9 | import ComponentInteractivityMixin from 'ember-interactivity/mixins/component-interactivity';
10 | import MockInteractivityTrackingService from 'ember-interactivity/test-support/mock-interactivity-tracking-service';
11 |
12 | const COMPONENT_NAME = 'foo-bar';
13 |
14 | const InteractivityStub = Service.extend({
15 | didReporterBecomeInteractive() {},
16 | didReporterBecomeNonInteractive() {},
17 | subscribeComponent() {},
18 | unsubscribeComponent() {}
19 | });
20 |
21 | module('Unit | Mixin | component interactivity', function (hooks) {
22 | setupTest(hooks);
23 |
24 | hooks.beforeEach(function () {
25 | this.BaseObject = EmberObject.extend(ComponentInteractivityMixin, {
26 | interactivity: InteractivityStub.create(),
27 | interactivityTracking: MockInteractivityTrackingService.create(),
28 | toString() {
29 | return `
34 | 
56 |
57 |
58 | 35 | Using Google's RAIL model, 36 | we learn to focus on the more critical aspects of a page or component 37 | in order to improve the user's perception application speed. We define 38 | Time to Interactivity to be the time it takes for the user to perceive 39 | that the application is ready for interaction. 40 | 41 | Ember Interactivity allows us to generate latency metrics tailored to this definition; 42 | specifically, by identifying the critical components required to render a parent 43 | route or component, we can track load times and identify bottlenecks that are 44 | critical to the user experience. By focusing on perceived load times, we are 45 | able to reduce user bounce rates and churn through making the content appear to 46 | load faster. Some strategies for this involve adding placeholders for necessarily 47 | long content wait times, but often there is plenty of low-hanging fruit to make 48 | actual improvements if we have the proper instrumentation to locate these issues. 49 |
50 |51 | Try 52 | Performance Profiling 53 | in Chrome DevTools to see the route & components below show up under "User Timing": 54 |
55 |
56 | 59 | 60 | {{parent-interactivity}} 61 |
I am a basic template with no child components.
122 | ``` 123 | 124 | ```javascript 125 | // components/foo-bar.js 126 | import Component from '@ember/component'; 127 | import { run } from '@ember/runloop'; 128 | import ComponentInteractivity from 'ember-interactivity/mixins/component-interactivity'; 129 | 130 | export default Component.extend(ComponentInteractivity, { 131 | didInsertElement() { 132 | this._super(...arguments); 133 | run.scheduleOnce('afterRender', this, this.reportInteractive); 134 | } 135 | }); 136 | ``` 137 | 138 | If your component relies on asynchronous behavior (such as data loading), 139 | you can delay your `afterRender` scheduling until after that behavior completes. 140 | 141 | ```javascript 142 | // components/foo-bar.js 143 | import Component from '@ember/component'; 144 | import { run } from '@ember/runloop'; 145 | import ComponentInteractivity from 'ember-interactivity/mixins/component-interactivity'; 146 | 147 | export default Component.extend(ComponentInteractivity, { 148 | init() { 149 | this._super(...arguments); 150 | 151 | this.loadData().then(() => { 152 | run.scheduleOnce('afterRender', this, this.reportInteractive); 153 | }); 154 | } 155 | }); 156 | ``` 157 | 158 | For components that rely on their child components to be interactive, 159 | read how to utilize the [isInteractive](#isInteractive) method. 160 | 161 | ### isInteractive 162 | 163 | In order to instrument latency more accurately, we define the list of 164 | components we expect to report as interactive in order to complete 165 | the critical rendering path of the route/component (known as the "subscriber"). 166 | This is handled by implementing an [`isInteractive` method](https://github.com/elwayman02/jordan-hawker/blob/master/app/routes/music.js#L4-L6) 167 | in each subscriber. This method is passed a function that will tell you if a reporter is interactive. 168 | 169 | ```javascript 170 | // routes/foo.js or components/foo-bar.js 171 | isInteractive(didReportInteractive) { 172 | return didReportInteractive('first-component') && didReportInteractive('second-component'); 173 | } 174 | ``` 175 | 176 | Pass `didReportInteractive` the name of a component the subscriber renders 177 | that is considered critical for interactivity. Once `isInteractive` 178 | returns true, the relevant tracking events will be fired. 179 | 180 | If you expect the subscriber to render multiple instances of the same component 181 | (e.g. an `#each` loop), you can [pass the expected number](https://github.com/elwayman02/jordan-hawker/blob/master/app/components/github-projects.js#L28-L30) 182 | to `didReportInteractive`: 183 | 184 | ```javascript 185 | // routes/foo.js or components/foo-bar.js 186 | isInteractive(didReportInteractive) { 187 | let count = this.get('someData.length'); 188 | return didReportInteractive('first-component', { count }) && didReportInteractive('second-component'); 189 | } 190 | ``` 191 | 192 | If there are multiple interactivity states to consider, simply add those 193 | conditions to `isInteractive`: 194 | 195 | ```handlebars 196 | // templates/foo.hbs or templates/components/foo-bar.hbs 197 | {{if someState}} 198 | {{first-component}} 199 | {{else}} 200 | {{second-component}} 201 | {{/if}} 202 | ``` 203 | 204 | ```javascript 205 | // routes/foo.js or components/foo-bar.js 206 | isInteractive(didReportInteractive) { 207 | if (this.get('someState')) { 208 | return didReportInteractive('first-component'); 209 | } 210 | return didReportInteractive('second-component'); 211 | } 212 | ``` 213 | 214 | ### Beacons 215 | 216 | Often a template has multiple rendering states (e.g. a loading state), 217 | which may or may not render child components. If such a situation occurs, 218 | neither basic or complex instrumentation is a perfect fit. To address this, 219 | Ember Interactivity provides an `interactivity-beacon` component. These 220 | beacons are simple components that you can append to the end of a template 221 | block in order to time the rendering of that block. 222 | 223 | Provide the beacon with a `beaconId` to give it a unique identifier: 224 | 225 | ```handlebars 226 | // routes/foo.js or components/foo-bar.js 227 | {{#if isLoading}} 228 |Loading...
229 | {{interactivity-beacon beaconId='foo-loading'}} 230 | {{else}} 231 | {{first-component}} 232 | {{second-component}} 233 | {{/if}} 234 | ``` 235 | 236 | Each `beaconId` is prepended with 'beacon:' for use in `didReportInteractive`: 237 | 238 | ```javascript 239 | // routes/foo.js or components/foo-bar.js 240 | isInteractive(didReportInteractive) { 241 | if (this.get('isLoading')) { 242 | return didReportInteractive('beacon:foo-loading'); 243 | } 244 | return didReportInteractive('first-component') && didReportInteractive('second-component'); 245 | } 246 | ``` 247 | 248 | ### Tracking 249 | 250 | Ember Interactivity sends its events to the `interactivity-tracking` service. 251 | Use this interface to implement your own integration points for sending data 252 | to your favorite analytics service. For example, if you want to use [`ember-metrics`](https://github.com/poteto/ember-metrics) 253 | to send interactivity events to Mixpanel: 254 | 255 | ```javascript 256 | // app/services/interactivity-tracking.js 257 | import { inject as service } from '@ember/service'; 258 | import InteractivityTrackingService from 'ember-interactivity/services/interactivity-tracking'; 259 | 260 | export default InteractivityTrackingService.extend({ 261 | metrics: service(), 262 | 263 | trackComponent(data) { 264 | this.get('metrics').trackEvent('mixpanel', data); 265 | } 266 | 267 | trackRoute(data) { 268 | this.get('metrics').trackEvent('mixpanel', data); 269 | } 270 | }); 271 | ``` 272 | 273 | The interface is simple; it just passes through a data object for 274 | various events, and you can handle them however you like. All data will 275 | include an `event` name as detailed below; you can map these strings to 276 | whatever names you prefer for sending to your analytics service. 277 | 278 | #### trackRoute 279 | 280 | This method is called whenever a route interactivity event is triggered. 281 | There are three possible events: `routeInitializing`, `routeActivating`, & `routeInitialized` 282 | 283 | These events are useful for segmenting your route latency numbers to know 284 | if bottlenecks are caused by your APIs, the actual content rendering, or 285 | some upstream app dependency (such as the CDN). Each `trackRoute` event 286 | passes the following base data: 287 | 288 | * event - The name of the event (e.g. `routeInitializing`) 289 | * clientTime - The time the event occurred, formatted as a Float 290 | * destination - The destination route for the transition 291 | * routeName - The name of the route this event belongs to 292 | * lostVisibility - Whether or not the app lost visibility 293 | 294 | When `routeName` and `destination` are the same, you are on a leaf route 295 | (as opposed to a parent route whose hooks trigger as part of the rendering process). 296 | By default only leaf routes report interactivity, so while all routes will fire 297 | `routeInitializing` & `routeActivating` events, only leaf routes 298 | (or routes where `isInteractive` is defined) send `routeInitialized`. 299 | 300 | ###### Visibility Tracking 301 | 302 | Ember Interactivity uses [`ember-is-visible`](https://github.com/elwayman02/ember-is-visible) 303 | to track if the document loses visibility while the route is loading. This is 304 | useful because the browser may de-optimize loading some part of your application 305 | when a user switches tabs to another site. Using this data, we can identify events 306 | where latency numbers may be increased due to visibility loss, as well as 307 | track user behavior to know if they are frequently moving away from the site 308 | while waiting for it to load. 309 | 310 | ##### routeInitializing 311 | 312 | This event is called from the `beforeModel` hook of your route and 313 | indicates the beginning of each route's loading phases. 314 | 315 | ##### routeActivating 316 | 317 | This event is called when the `activate` hook is triggered, after the model hooks complete. 318 | This is the point at which the route will begin scheduling its rendering tasks. 319 | 320 | ##### routeInteractive 321 | 322 | This event is called when the route reports itself as interactive, per the definitions 323 | outlined above. In addition to the base data, two additional properties are added to this event: 324 | 325 | * isAppLaunch - Boolean indicating if the app is launching for first time 326 | or if this is a transition from another route. 327 | * timeElapsed - This indicates the time (in milliseconds) that the route 328 | took to become interactive since the initial browser fetch. Only included 329 | if `isAppLaunch` is true. 330 | 331 | `timeElapsed` is usually your primary data point for tracking the load times of your routes. 332 | 333 | #### trackComponent 334 | 335 | This method is called whenever a component interactivity event is triggered. 336 | There are two possible events: `componentInitializing` & `componentInteractive` 337 | 338 | Event data contains the following properties: 339 | 340 | * event - The name of the event (e.g. `componentInteractive`) 341 | * clientTime - The time the event occurred, formatted as a Float 342 | * component - The name of the component 343 | * componentId - A unique id for the component (to differentiate instances of the same component) 344 | 345 | The `componentInteractive` event adds an additional property: 346 | 347 | * timeElapsed - This indicates the time (in milliseconds) that the component 348 | took to become interactive since it began initializing. 349 | (Essentially subtracting the clientTimes for the two events) 350 | 351 | ##### isComponentInstrumentationDisabled 352 | 353 | This method allows you to control whether components are instrumented in the application. 354 | By default, it reads the configuration property [`tracking.disableComponents`](#Configuration), 355 | but you can override the method to add custom logic for when to disable instrumentation. 356 | 357 | #### trackError (_Experimental_) 358 | 359 | This method is called whenever an error occurs in Ember Interactivity. 360 | Currently, no data is sent along with an error; please file issues if you 361 | have requests for data to include! `trackError` is only hooked up for routes 362 | at the moment, such as when a user has transitioned away from the route before completion. 363 | 364 | ### Timeline Marking 365 | 366 | Ember Interactivity automatically marks each route/component using the 367 | [Performance Timeline](https://developer.mozilla.org/en-US/docs/Web/API/Performance_Timeline/Using_Performance_Timeline) 368 | standard. DevTools such as the [Chrome Timeline](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference) 369 | can display the timings for easy visualization of the critical rendering waterfall. 370 | This can help developers identify bottlenecks for optimizing time to interactivity. 371 | 372 |  373 | 374 | Note: It's important to realize that in some cases, components you may not have 375 | considered to be critical are creating rendering bottlenecks in your application. 376 | Look for suspicious gaps in the rendering visualization to identify these situations. 377 | 378 | ### Configuration 379 | 380 | Developers can toggle individual features of Ember Interactivity by 381 | adding an `interactivity` object to their application's environment config. 382 | This can be useful if you only want features run in certain environments, 383 | or if you want to sample a percentage of your users to stay within data storage limits. 384 | 385 | Three features can be configured: 386 | 387 | * `instrumentation` - Toggle instrumentation altogether (Note: Does not support leaf/parent configs below) 388 | * `timelineMarking` - Toggle marking the performance timeline 389 | * `tracking` - Toggle sending tracking events 390 | 391 | Each feature can be configured for four subsets of the addon: 392 | 393 | * `disableComponents` - Set true to disable for all components 394 | * `disableLeafComponents` - Set true to disable for child components 395 | (those that do not implement `isInteractive`). This is useful if you 396 | only want a feature enabled for subscribers (parent routes/components). 397 | * `disableRoutes` - Set true to disable for all routes 398 | * `disableParentRoutes` - Set true to disable for all non-leaf routes 399 | (those that are not the target of a transition). This is useful if you 400 | aren't trying to identify bottlenecks in your route chain and just want 401 | to collect latency numbers for each transition. 402 | 403 | ```javascript 404 | // config/environment.js 405 | module.exports = function (environment) { 406 | let ENV = { 407 | interactivity: { 408 | tracking: { 409 | disableLeafComponents: true 410 | }, 411 | timelineMarking: { 412 | disableRoutes: true 413 | } 414 | } 415 | }; 416 | return ENV; 417 | }; 418 | ``` 419 | 420 | #### Overrides 421 | 422 | TODO: Per-instance Overrides 423 | 424 | ### Testing 425 | 426 | Ember Interactivity provides a number of test helpers to support testing your application's latency instrumentation. 427 | 428 | #### Mock Services 429 | 430 | Mock service instances are provided for your use. It is recommended to 431 | register these mock services in each of the tests of your application. 432 | 433 | ```javascript 434 | import MockInteractivityService from 'ember-interactivity/test-support/mock-interactivity-service'; 435 | import MockInteractivityTrackingService from 'ember-interactivity/test-support/mock-interactivity-tracking-service'; 436 | 437 | module('foo', 'Integration | Component | foo', function (hooks) { 438 | setupRenderingTest(hooks); 439 | 440 | hooks.beforeEach(function () { 441 | this.owner.register('service:interactivity', MockInteractivityService); 442 | this.owner.register('service:interactivity-tracking', MockInteractivityTrackingService); 443 | }); 444 | }); 445 | ``` 446 | 447 | To avoid writing this for every test in your application, you can write 448 | a wrapper around `module` that handles registering any mock services for your tests. 449 | 450 | #### Interactivity Assertions 451 | 452 | The `assert-interactivity` helper provides methods to test that your routes/components 453 | are correctly reporting latency events when rendering. As your tests exercise 454 | these modules, these assertions will confirm the interactivity events get sent. 455 | This helper relies on the `MockInteractivityService` being registered. 456 | 457 | First, make the assertion available to your tests: 458 | 459 | ```javascript 460 | // tests/test-helper.js 461 | import 'ember-interactivity/test-support/assert-interactivity'; 462 | ``` 463 | 464 | Then, use the `trackInteractivity` assertion in your tests for routes and component subscribers: 465 | 466 | ```javascript 467 | // tests/acceptance/foo.js 468 | import { module, test } from 'qunit'; 469 | import { click, fillIn, visit } from '@ember/test-helpers'; 470 | import { setupApplicationTest } from 'ember-qunit'; 471 | 472 | module('Acceptance | foo', function (hooks) { 473 | setupApplicationTest(hooks); 474 | 475 | test('should report interactive', async function (assert) { 476 | await visit('/foo'); 477 | assert.trackInteractivity('foo'); 478 | }); 479 | }); 480 | ``` 481 | 482 | Let's say you want to simulate some async behavior and make sure interactivity 483 | conditions aren't being fulfilled prematurely. The `trackNonInteractivity` 484 | assertion can be used to test this scenario: 485 | 486 | ```javascript 487 | // tests/acceptance/foo.js 488 | import { module, test } from 'qunit'; 489 | import { click, fillIn, visit } from '@ember/test-helpers'; 490 | import { setupApplicationTest } from 'ember-qunit'; 491 | 492 | module('Acceptance | foo', function (hooks) { 493 | setupApplicationTest(hooks); 494 | 495 | hooks.beforeEach(function () { 496 | this.resolveAsyncBehavior = () => { 497 | // Do stuff to resolve interactivity conditions 498 | }; 499 | }); 500 | 501 | test('should report interactive', async function (assert) { 502 | await visit('/foo'); 503 | assert.trackNonInteractivity('foo'); 504 | this.resolveAsyncBehavior(); 505 | assert.trackInteractivity('foo'); 506 | }); 507 | }); 508 | ``` 509 | 510 | Contributing 511 | ------------------------------------------------------------------------------ 512 | 513 | We adhere to the [Ember Community Guidelines](https://emberjs.com/guidelines/) for our Code of Conduct. 514 | 515 | [](https://www.netlify.com) 516 | 517 | ### Installation 518 | 519 | * `git clone https://www.github.com/elwayman02/ember-interactivity.git` 520 | * `cd ember-interactivity` 521 | * `yarn install` 522 | 523 | ### Linting 524 | 525 | * `yarn lint:js` 526 | * `yarn lint:js --fix` 527 | 528 | ### Running tests 529 | 530 | * `ember test` – Runs the test suite on the current Ember version 531 | * `ember test --server` – Runs the test suite in "watch mode" 532 | * `ember try:each` – Runs the test suite against multiple Ember versions 533 | 534 | ### Running the dummy application 535 | 536 | * `ember serve` 537 | * Visit the dummy application at [http://localhost:4200](http://localhost:4200). 538 | 539 | For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/). 540 | 541 | License 542 | ------------------------------------------------------------------------------ 543 | 544 | This project is licensed under the [MIT License](LICENSE.md). 545 | --------------------------------------------------------------------------------