% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/st_metrics.R
\name{st_metrics}
\alias{st_metrics}
\title{Fetch Sensor Tower Metrics}
\usage{
st_metrics(
  app_id,
  metrics = c("revenue", "downloads"),
  os = "unified",
  countries = "WW",
  date_from = Sys.Date() - 90,
  date_to = Sys.Date(),
  granularity = "daily",
  revenue_unit = c("dollars", "cents"),
  shape = c("long", "wide"),
  cache = TRUE,
  auth_token = NULL
)
}
\arguments{
\item{app_id}{Character scalar or vector of app identifiers. Each entry can be
a Sensor Tower unified app ID, an iOS numeric app ID, or an Android package
name.}

\item{metrics}{Character vector of metrics to return. Supported values are
`"revenue"` and `"downloads"`.}

\item{os}{Character scalar. One of `"ios"`, `"android"`, or `"unified"`.}

\item{countries}{Character vector of 2-letter country codes. Use `"WW"` for
worldwide aggregates.}

\item{date_from, date_to}{Date bounds for the query. Accept `Date` objects or
ISO date strings.}

\item{granularity}{Character scalar. One of `"daily"`, `"weekly"`,
`"monthly"`, or `"quarterly"`.}

\item{revenue_unit}{Character scalar. `"dollars"` (default) returns revenue in
base currency units. `"cents"` returns revenue in cents for compatibility
with the legacy API surface.}

\item{shape}{Character scalar. `"long"` returns one row per metric observation.
`"wide"` returns one row per app/date/country with separate metric columns.}

\item{cache}{Logical. If `TRUE`, use a process-local cache keyed on the
normalized arguments.}

\item{auth_token}{Optional Sensor Tower API token. If `NULL`, falls back to
`SENSORTOWER_AUTH_TOKEN`.}
}
\value{
If `shape = "long"`, a tibble with columns:
  - `app_id`: identifier supplied to `st_metrics()`
  - `os`: normalized operating system
  - `country`: 2-letter country code
  - `date`: observation date
  - `metric`: one of `"revenue"` or `"downloads"`
  - `value`: metric value; revenue is in dollars by default and cents when
    `revenue_unit = "cents"`

If `shape = "wide"`, a tibble with columns:
  - `app_id`
  - `os`
  - `country`
  - `date`
  - one numeric column per requested metric
}
\description{
Thin v1.0.0 facade for sales/download metrics. The function validates a
standardized argument set, dispatches to the legacy implementation that best
matches the request, and then normalizes the result into a stable schema.
}
\examples{
\dontrun{
st_metrics(
  app_id = "553834731",
  os = "ios",
  countries = "US",
  date_from = Sys.Date() - 30,
  date_to = Sys.Date() - 1
)

st_metrics(
  app_id = c("553834731", "com.supercell.clashofclans"),
  os = "unified",
  shape = "wide",
  countries = c("US", "GB"),
  revenue_unit = "cents"
)
}

}
