@shopify/reportify-react
[![Build status](https://badge.buildkite.com/7a5a3c270fd33e1ddda58410d0278e033bc028841f5142f122.svg)](https://buildkite.com/shopify/reportify-react)
Last updated a month ago by shopify-dep .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @shopify/reportify-react 
SYNC missed versions from official npm registry.

Reportify React

Build status

IssuesShipit

@shopify/reportify-react is a package that helps you fetch and manage data from Reportify in your React applications.

Getting Started

Install the package in your react project to get started:

  • yarn add @shopify/reportify-react

There are 3 important parts of @shopify/reportify-react that you need to use to fetch data: ReportifyClient, ReportifyProvider, and useReportifyQuery. A quick sample follows this paragraph immediately, with more in-depth information below.

import {ReportifyClient, ReportifyProvider, useReportifyQuery} from '@shopify/reportify-react';

// Create the client
const client = new ReportifyClient({
  source: 'my-source',
  refetchToken: () => Promise.resolve('my-token'),
});

// Create a component
function TotalSales({start, end}) {
  const queryResult = useReportifyQuery(
    `SHOW total_sales FROM sales SINCE ${start} UNTIL ${end}`,
    {
      pollInterval: 5000,
    }
  );

  if (queryResult.isLoading) {
    return <p>Loading...</p>;
  } else if (queryResult.hasError) {
    console.log(queryResult.errorMessage);
    return <p style={{color: 'red'}}>There was an error! Check the console</p>;
  }

  return (
    <div>
      <p>Your total sales from {start} to {end} were {queryResult.response.result.data[0][0]}</p>
    </div>
  );
}

// Wrap your application in a ReportifyProvider
export default function App() {
  return (
    <ReportifyProvider client={client}>
      <TotalSales start="2017-01-01" end="today" />
    </ReportifyProvider>
  );
}

ReportifyClient

The Reportify client is the means by which you authenticate with and make requests to Reportify.

Options

Option Type Required? Description
source string The source parameter helps Reportify identify your client. It should describe your application. Ping #analytics-stack on Slack to find out more about the source param.
refetchToken (): Promise<string> refetchToken is a required function that tells the client how to fetch an auth token that can be used when querying Reportify. It takes no parameters and should return a Promise which resolves to a string.
hostName string Specify a Reportify endpoint to query. Default is https://analytics.shopify.com
token string You may provide an initial token to the client so that it does not need to call refetchToken on its first request.
maxRetries number Specify the maximum number of times the client should retry your query when receiving a failed response. Default is 1.

ReportifyProvider

The Reportify provider gives its children access to the reportify client. In most cases, you will not work directly with the Reportify client – simply put it high in your component tree and pass it an instance of ReportifyClient.

Options

Option Type Required? Description
client ReportifyClient An instance of ReportifyClient that will be used to query Reportify

useReportifyQuery

useReportifyQuery is a hook that helps you fetch data using ShopifyQL queries you provide.

Options

useReportifyQuery receives a query as the first argument and an options object with the following available properties as its second argument:

Option Type Description
pollInterval number or function The interval at which you would like the hook to poll for new data. If passed a function, the function will receive pollCount (the number of times the component has polled), previousPollInterval (the last poll interval passed or computed), and previousResponses (the last two responses to be returned from Reportify, with most recent first)
source string The source paramter helps Reportify identify your client. This will override the source given to ReportifyClient/ReportifyProvider for just this query.
dataOnly boolean Determines whether the Reportify response should contain metadata or just data.

useReportifyAST

useReportifyAST is a hook that fetches Reportify data formatted as an abstract syntax tree (AST).

Options

useReportifyAST receives a ShopifyQL query string as its first argument and an optional second argument in the form of an object with the following properties:

Option Type Description
source string The source paramter helps Reportify identify your client. This will override the source given to ReportifyClient/ReportifyProvider for just this query.

useReportifyAST returns an object containing the following parameters:

Option Type Description
ast Object An abstract syntax tree of the query results
loading boolean Represents whether or not the query is still loading
error boolean Represents whether or not the query returns an error

Example

const {ast, loading, error} = useReportifyAST('SHOW total_sales FROM sales SINCE -1d UNTIL -1d', {source: 'example'});

withReportify

withReportify is a decorator that wraps your components and provides data based on the ShopifyQL queries you provide it.

Options

withReportify receives a single options parameter with the following properties:

  • an optional source string that overrides the source options provided in the client.
  • a queries object. The queries object should have the name of the query as the key and an object with the following options as the value:
Option Type Required? Description
query string or function The query you want to send to Reportify. query accepts either a string or a function that will recieve the props passed from the parent component; the function should return a valid ShopifyQL string.
pollInterval number or function pollInterval is an optional parameter that defines how often react-reportify will poll for new data for the query being defined. It accepts either a number for a fixed interval or a function that receives the number of times the container has polled which should return a number as well as props passed from the parent component.
transform function transform is an optional parameter that defines how a ReportifyResponse will be transformed once the response is received. It should return a ReportifyResponse.
skip function skip is an optional parameter that allows for a query to be skipped. It is a function that receives props passed from the parent component; returning a truthy value will cause the query to be skipped and a falsey value will have normal behavior. Polling is not affected by skipping and timers will restart as soon as a query is determined to be in need of skipping.

Examples

Here are a few examples of options passed to withReportify:

Two queries

withReportify({
  queries: {
    totalSales: {
      query: 'SHOW total_sales FROM sales SINCE yesterday UNTIL today',
    },
    sessions: {
      query: 'SHOW total_sessions FROM visits SINCE yesterday UNTIL today',
    },
  },
});

Dynamic, polling query

withReportify({
  queries: {
    salesDateRange: {
      // `query` receives props passed into the component – in this case,
      // that might be something like <MyComponent start="2018-01-01" end="2018-01-31">
      query: ({start, end}) => `SHOW total_sales FROM sales SINCE ${start} UNTIL ${end}`,

      // Pass a function that slows down polling as time goes on
      pollInterval: (pollCount) => pollCount * 5000,
    },
  },
});

A query with a source

withReportify({
  source: 'my-custom-source',
  queries: {
    totalSales: {
      query: 'SHOW total_sales FROM sales SINCE yesterday UNTIL today',
    },
  },
});

<Query />

<Query /> is an alternative way to fetch data that relies on a render prop instead of wrapping your component.

Props

Prop Type Required? Description
queries {[handle: string]: string} The query that will be sent to Reportify.
source string The source paramter helps Reportify identify your client. This will override the source given to ReportifyClient/ReportifyProvider for just this query.
children (queryResults: ResultMap<ResponseShape>): React.ReactNode A render function that query results are passed to
combineUpdates boolean Wait for all queries to finish before passing data to children

withReportifyClient

Sometimes you will need direct access to the methods the client has to help query reportify. When that is the case, you can decorate your component with withReportifyClient.

withReportifyClient()(MyComponent);

In the example above, MyComponent will receive a new prop -- reportifyClient -- with the following methods:

Method Description
query(shopifyql: string, options?: {endpoint?: string, beta?: boolean, handle?: string, source?: string}): Promise<ReportifyResponse> Dispatch a reportify query. Calls to query will be batched, just like
withReportify.
exportQueryURL(shopifyql: string, filename: string): Promise<string> Create a URL that can be used to export a report for the given ShopifyQL query as a CSV.
fetchCSV(shopifyql: string): Promise<string> Returns a Blob containing the query result as a CSV

An example using exportQueryURL

class MyComponent extends React.Component {
  render() {
    return <button onClick={this.handleClick}>✨</button>;
  }

  handleClick = async () => {
    const {reportifyClient} = this.props; // `reportifyClient` comes from `withReportifyClient` below

    const exportUrl = await reportifyClient.exportQueryURL(
      'SHOW total_sales FROM sales SINCE -1d UNTIL today',
      'my_exported_report',
    );

    window.location = exportUrl;
  }
}

withReportifyClient()(MyComponent);

An example using fetchCSV

class MyComponent extends React.Component {
  render() {
    return 
    <>
      <button onClick={this.handleClick}>✨</button>
      <FileDownloader blob={exportBlob} filename={'test_file'} />
    </>
  }

  handleClick = async () => {
    const {reportifyClient} = this.props; // `reportifyClient` comes from `withReportifyClient` below

    const csvBlob = await reportifyClient.fetchCSV(
      'SHOW total_sales FROM sales SINCE -1d UNTIL today'
    );
    
    this.setState({
      exportBlob: csvBlob,
    });
  }
}

withReportifyClient()(MyComponent);

Current Tags

  • 3.5.0                                ...           latest (a month ago)
  • 1.4.0-alpha.1                                ...           next (2 years ago)

46 Versions

  • 3.5.0                                ...           a month ago
  • 3.4.4                                ...           4 months ago
  • 3.4.3                                ...           5 months ago
  • 3.4.2 [deprecated]           ...           5 months ago
  • 3.4.1 [deprecated]           ...           5 months ago
  • 3.4.0                                ...           6 months ago
  • 3.3.0                                ...           6 months ago
  • 3.2.0                                ...           8 months ago
  • 3.1.0                                ...           9 months ago
  • 3.0.0                                ...           10 months ago
  • 2.11.1                                ...           a year ago
  • 2.11.0                                ...           a year ago
  • 2.10.0                                ...           a year ago
  • 2.9.3                                ...           a year ago
  • 2.9.2                                ...           a year ago
  • 2.9.1                                ...           a year ago
  • 2.9.0                                ...           a year ago
  • 2.8.0                                ...           a year ago
  • 2.7.0                                ...           2 years ago
  • 2.6.0                                ...           2 years ago
  • 2.5.2                                ...           2 years ago
  • 2.5.1                                ...           2 years ago
  • 2.5.0                                ...           2 years ago
  • 2.4.0                                ...           2 years ago
  • 2.3.2                                ...           2 years ago
  • 2.3.1                                ...           2 years ago
  • 2.3.0                                ...           2 years ago
  • 2.2.0                                ...           2 years ago
  • 2.1.1                                ...           2 years ago
  • 2.1.0                                ...           2 years ago
  • 2.0.1                                ...           2 years ago
  • 2.0.0                                ...           2 years ago
  • 1.6.0                                ...           2 years ago
  • 1.5.0                                ...           2 years ago
  • 1.4.5                                ...           2 years ago
  • 1.4.4                                ...           2 years ago
  • 1.4.3                                ...           2 years ago
  • 1.4.2                                ...           2 years ago
  • 1.4.1                                ...           2 years ago
  • 1.4.0                                ...           2 years ago
  • 1.4.0-alpha.1                                ...           2 years ago
  • 1.3.0                                ...           2 years ago
  • 1.2.0                                ...           2 years ago
  • 1.1.0                                ...           2 years ago
  • 1.0.1-alpha.2                                ...           2 years ago
  • 1.0.0                                ...           2 years ago
Downloads
Today 1
This Week 1
This Month 1
Last Day 0
Last Week 1
Last Month 13
Dependencies (4)
Dev Dependencies (22)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |