Skip to content

Commit 5615f4b

Browse files
whizsidwhizsid
committed
Added package README file
1 parent 6410997 commit 5615f4b

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

  • packages/google-analytics-embed-react

‎packages/google-analytics-embed-react/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# google-analytics-embed-react
2+
3+
Bringing the Google Analytics Embed Components for your ReactJS admin
4+
panels.
5+
6+
## Installation
7+
8+
```
9+
npm install google-analytics-embed-react
10+
```
11+
12+
## Usage
13+
14+
You need to wrap your entire app with the `GoogleAnalyitcsProvider`
15+
component as the first step to use this library. This component will
16+
take the `accessToken` as the only mandatory prop. But it is also
17+
optional :smiley:. It means you do not need the accessToken in first
18+
rendering time. But you have to pass it later to display your graphs.
19+
20+
```jsx
21+
<GoogleAnalyticsProvider accessToken={myAccessToken}>
22+
{/* Your application components */}
23+
</GoogleAnalyticsProvider>
24+
```
25+
26+
Then render any chart component in your application.
27+
28+
```
29+
<GoogleAnalyticsPieChart
30+
query={{
31+
ids, // <-- Replace with the ids value for your view.
32+
'start-date': '90daysAgo',
33+
'end-date': 'today',
34+
metrics:
35+
'ga:pageviews,ga:uniquePageviews,ga:timeOnPage,ga:bounces,ga:entrances,ga:exits',
36+
sort: '-ga:pageviews',
37+
dimensions: 'ga:pagePath',
38+
'max-results': 10
39+
}}
40+
width={500}
41+
style={{ float: 'left' }}
42+
pieHole={0.4}
43+
/>
44+
```
45+
46+
## Component Reference
47+
48+
### GoogleAnalyticsProvider
49+
50+
This component will load the Google platform script and authenticate
51+
yourself with the `gapi.analytics` namespace.
52+
53+
#### Props
54+
55+
| Name | Type | Default | Optional | Description |
56+
| ------------------------ | -------------------- | --------- | -------- | ------------------------------------------------------------------------------------- |
57+
| `accessToken` | string | undefined | No\* | Access token to authroize the user |
58+
| `onReady` | callback, `()=>void` | undefined | Yes | Fired once the Google platform script loaded and gapi is ready to use. |
59+
| `onAuthenticated` | callback, `()=>void` | undefined | Yes | Fired once the Google Analytics API authenticated the access token |
60+
| `scopes` | array, `string[]` | undefined | Yes | Additional scopes to include |
61+
| `overwriteDefaultScopes` | boolean | false | Yes | Overwrite the scopes passed when generating the access token with the provided scopes |
62+
| `children` | `JSX.Element` | N/A | No | Child elements of the application to render inside the provider |
63+
64+
### ViewSelector
65+
66+
This is the react implementation of the [View
67+
Selector](https://developers.google.com/analytics/devguides/reporting/embed/v1/component-reference#viewselector).
68+
Users can select their Google Analytics view from the select boxes. Then
69+
you will be notified by the `onChange` callback.
70+
71+
#### Props
72+
73+
| Name | Type | Default | Optional | Description |
74+
| ----------- | ----------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
75+
| `onChange` | callback, `(string)=>void` | undefined | Yes | Fired at the component initialization time and the user changed the view. The first argument is the view id in `ga:xxxxx` format. |
76+
| `children` | `JSX.Element` | undefined | Yes | An optional placeholder to show until the gapi is being ready |
77+
| `style` | object, `React.CSSProperties` | undefined | Yes | CSS styles to pass to the container element. |
78+
| `className` | string | undefined | Yes | Class name to pass to the container element |
79+
80+
### DataChart
81+
82+
`GoogleAnalyticsLineChart`, `GoogleAnalyticsBarChart`,
83+
`GoogleAnalyticsColumnChart`, `GoogleAnalyticsGeoChart`,
84+
`GoogleAnalyticsPieChart` , `GoogleAnalyticsTable` components will help
85+
you to visualize the Google Analytics Data by using the
86+
`google.visualization` API. All of those components extended to the same
87+
`DataChart` component and the props are common for all components.
88+
89+
#### Props
90+
91+
| Name | Type | Default | Optional | Description |
92+
| ----------- | ------------------------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93+
| `query` | object, `gapi.analytics.Query` | N/A | No | Refer the [Google Core Reporting API](https://developers.google.com/analytics/devguides/reporting/core/v3/reference#q_summary) for more details about the properties and filterations. |
94+
| `children` | `JSX.Element` | undefined | Yes | An optional placeholder to show until the gapi is being ready |
95+
| `style` | object, `React.CSSProperties` | undefined | Yes | CSS styles to pass to the container element. |
96+
| `className` | string | undefined | Yes | Class name to pass to the container element |
97+
| `onSuccess` | callback, `(object)=>void` | undefined | Yes | Fired when the chart successfully rendered and the Reporting API call success. First argument is a response object that returning from Reporting API. Check this [page](https://developers.google.com/analytics/devguides/reporting/core/v3/reference#data_response) for more details. |
98+
| `onError` | callback, `(object)=>void` | undefined | Yes | Fired when an error occured during the rendering the chart or a error response received from the Reporting API. The first argument contains the error object. Refer this [page](https://developers.google.com/analytics/devguides/reporting/core/v3/errors) for more details about error response object. |
99+
| . . . | object | undefined | Yes | Google Chart options depending on the chart type. Refer the [Google Charts Guides](https://developers.google.com/chart/interactive/docs) to get a knowledge about options needed for different chart types. |
100+
101+
### Data
102+
103+
This is the implementation for
104+
[Data](https://developers.google.com/analytics/devguides/reporting/embed/v1/component-reference#data)
105+
component. We implemented it as a helper method to fetch Reporting data
106+
manually.
107+
108+
```
109+
fetchData(query: Query): Promise<SuccessResponse>
110+
```
111+
112+
This method will return a Promise which resolve when the Reporting API
113+
returned a [success response](https://developers.google.com/analytics/devguides/reporting/core/v3/reference#data_response).
114+
And it will be rejected if the Reporting API returned an [error
115+
response](https://developers.google.com/analytics/devguides/reporting/core/v3/errors).
116+
This method will take a [query](https://developers.google.com/analytics/devguides/reporting/core/v3/reference#q_summary) as the only argument.
117+

0 commit comments

Comments
 (0)