Is it safe to call global.performance.reportFullyDrawn directly instead of using useReportFullyDrawn?

Vega Open Beta Q&A
1

Background

I am trying to measure app launch time (TTFD) using the @amazon-devices/kepler-performance-api package.

The official documentation recommends using the useReportFullyDrawn() hook, but I have a use case where I need to emit the fully_drawn marker from outside a React component (i.e., a non-React context). For this reason, I am considering calling global.performance.reportFullyDrawn directly, which appears to be the underlying implementation used by the hook.

Questions

1. Is it safe to call global.performance.reportFullyDrawn directly?

Since useReportFullyDrawn is a React hook, it can only be called inside a React component. I would like to know whether calling global.performance.reportFullyDrawn(...) directly from a non-React context or a utility function is a supported usage, or whether it is considered an unsupported internal API that may break in future versions.

2. Is it safe to pass null or an empty value for the rootTag argument?

Looking at the internal implementation of the hook, I can see that it retrieves rootTag from RootTagContext and passes it to global.performance.reportFullyDrawn(rootTag). When calling the function directly outside of a React context, RootTagContext is not accessible, so rootTag would need to be passed as null or an empty value. Would this cause any issues with TTFD measurement?

3. Is it safe to call reportFullyDrawn multiple times during app launch?

I am considering an implementation that calls reportFullyDrawn at different points to handle both cold start and warm start scenarios. If the function is called multiple times within a single launch lifecycle, could this corrupt trace data or cause a crash?

Environment

  • Package: @amazon-devices/kepler-performance-api v0.1.2

  • Related hook: useReportFullyDrawn

Thank you in advance for your help.

3

Hi @ishijima_tatsuki_1,

Thank you for your question about calling global.performance.reportFullyDrawn directly instead of using useReportFullyDrawn.

Our team is looking into it and will provide an update as soon as we have more information.

Thanks for helping us improve the Vega platform.

Warm regards,
Aishwarya

5

Hi @ishijima_tatsuki_1 ,

Here are the details for your questions:

1. Is it safe to call global.performance.reportFullyDrawn directly?

A. There is no non-hook alternative as a standalone function export. Calling global.performance.reportFullyDrawn(…) directly is relying on an internal implementation detail. It’s not part of the public API surface, which means: It could change or be removed in a future SDK version without notice

For non-React context use case, here is an approach that stay within the supported API:

Thin wrapper component — create a minimal React component whose sole job is to call useReportFullyDrawn() and expose the callback via a ref or event emitter that your non-React code can trigger:
import { useReportFullyDrawn } from ‘@amazon-devices/kepler-performance-api’;
import { useEffect } from ‘react’;
import { fullyDrawnEmitter } from ‘./fullyDrawnEmitter’;

export const FullyDrawnBridge = () => {
const reportFullyDrawn = useReportFullyDrawn();

useEffect(() => {
const sub = fullyDrawnEmitter.addListener(‘report’, () =>

{ reportFullyDrawn(); }
);
return () => sub.remove();
}, [reportFullyDrawn]);

return null; // renders nothing
};
Then from your non-React utility code: fullyDrawnEmitter.emit(‘report’).

2. Is it safe to pass null or an empty value for the rootTag argument?

WIP.. team is checking

3. Is it safe to call reportFullyDrawn multiple times during app launch?

Yes, calling it multiple times is safe — it won’t crash or corrupt trace data.

Here’s why: reportFullyDrawn emits a fully_drawn trace marker into the Perfetto trace. Each call writes a separate marker event with a timestamp. The KPI Visualizer’s trace analyzer only uses the first occurrence of fully_drawn after the launch start marker to compute TTFD. Subsequent calls are simply ignored during analysis.

For more details you can check with your Amazon contact.

Thanks,
Rohit

6

Hi @Amz_Rsk

Thank you for the detailed response!

I have understood your answers to questions 1 and 3.

Regarding question 1, I now understand that calling global.performance.reportFullyDrawn directly relies on an internal implementation detail and is not recommended.

Regarding question 2, since your answer to question 1 already makes it clear that directly calling the internal API is not the recommended approach, there is no need to investigate further.

Thanks again for your help, Rohit!