R client library for the Adobe Analytics 1.4 API - the API is currently in beta. This package hasn't been extensively tested, so please get in touch with me if you're interested in using it.
R
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
R
man
.gitignore
DESCRIPTION
NAMESPACE
README.md

README.md

RAA - Active development is now taking place in collaboration with Randy Zwitch under RSiteCatalyst (version_1_4)

Pronounced RAAAH! (imagine you are a ferocious lion).

R client library for the Adobe Analytics 1.4 API, currently in beta, but due out in Feb 2014. Get in touch with me if you're interested in using it. It is functional, but has not been extensively tested.

This library borrows from Randy Zwitch's excellent RSiteCatalyst package which provides access to the Adobe Analytics v1.3 API. RSiteCatalyst is on CRAN, so if you're looking for something tried and tested, that may be a better option. Install using install.packages("RSiteCatalyst").

Installation

RAA is in development, and is not yet on CRAN. You will need to install directly from GitHub.

First, install and load devtools:

install.packages("devtools")
library(devtools)

And then run install_github to install RAA.

install_github("RAA","willempaling")

And finally you are ready to load i t.

library(RAA)

You may also need to install other packages that RAA depends on.

If you want to use the OAUTH auth method, you'll also need:

For the legacy auth method (username/shared secret) you'll also need the following:

  • digest (only required for legacy auth method)
  • base64enc (only required for legacy auth method)
install.packages(c("jsonlite","plyr","httr","stringr","digest","base64enc,"httpuv","Rook"))

And if you're installing the dev branch of HTTR:

library(devtools)
install_github('httr')

Authorisation

Authorisation can be done using the legacy auth method (username:company + shared secret), or using the newer OAUTH method. Either is fine, but ultimately you should move towards using the OAUTH method, as the legacy auth method is deprecated.

Using OAUTH

First you will need to create an application in the Adobe Dev Center. The application name can be whatever you want. The redirect URI should be left blank.

This will provide you with a identifier and secret that you can use to access the Adobe Analytics API.

You currently need to specify your own endpoint. Once the 1.4 API is released, I'll update this to automatically retrieve your company endpoint.

RAA_Auth("your_identifier", 
         "your_secret", 
         endpoint.url="https://your-endpoint.omniture.com/admin/1.4/rest/")
Using legacy auth (web service credentials)

This auth method is pretty straight-forward, though much more fiddly involved under the hood, which is why it is deprecated.

You will simply need your username, and your shared secret, which you can retrieve from your account settings page in the Adobe Analytics web interface.

RAA_Auth("your_username:your_company", 
         "your_shared_secret", 
         endpoint.url="https://your-endpoint.omniture.com/admin/1.4/", 
         auth.method='legacy')

Running Reports

Once you've authorised, reports can be queued and retrieved using the helper libraries for each report type, or by using raw JSON report definitions.

Running a report using a JSON definition

The following code defines a JSON report description, and runs it. As no date granularity is specified, it will return a ranked report.

report.desc <- '{ "reportDescription" : { 
"dateFrom" : "2014-01-01", 
"dateTo" : "2014-11-07", 
"reportSuiteID" : "your_report_suite", 
"metrics" : [ { "id" : "pageviews" } ], 
"elements" : [ { "id" : "page" } ]
} }'

report.data <- JsonQueueReport(desc)

This is the same report description, but with daily date granularity, which will return a trended report.

report.desc <- '{ "reportDescription" : { 
"dateFrom" : "2014-01-01", 
"dateTo" : "2014-11-07", 
"dateGranularity" : "day", 
"reportSuiteID" : "your_report_suite", 
"metrics" : [ { "id" : "pageviews" } ], 
"elements" : [ { "id" : "page" } ]
} }'

report.data <- JsonQueueReport(desc)

Using the report helper functions

RAA has helper functions that make it easier to generate all report types (ranked, overtime, trended, pathing, fallout). These take parameters in R, convert them to JSON, then call JsonQueueReport. RAA helper functions do not yet support inline segmentation or search, so if you want to use that functionality, you will need to use JsonQueueReport directly.

QueueOvertime

Returns an overtime report. This is similar to the key metrics report, in that the only granularity allowed is time.

QueueOvertime requires a start and end date, a reportsuite ID, and a character vector of metrics.

date.from <- "2014-01-01"
date.to <- "2013-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews")

report.data <- QueueOvertime(reportsuite.id, date.from, date.to, metrics)

You may also wish to set any of the 5 optional named parameters.

date.from <- "2014-01-01"
date.to <- "2014-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews")
date.granularity <- "hour"
segment.id <- "Visit_Natural_Search"
anomaly.detection <- TRUE
data.current <- TRUE
expedite <- TRUE

report.data <- QueueOvertime(reportsuite.id, date.from, date.to, metrics,date.granularity=date.granularity,segment.id=segment.id,anomaly.detection=anomaly.detection,data.current=data.current,expedite=expedite)

QueueRanked

Returns a ranked report. This is an ordered list of elements and associated metrics with no time granularity.

QueueRanked requires a start and end date, a reportsuite ID, a character vector of elements and a character vector of metrics.

date.from <- "2014-01-01"
date.to <- "2014-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews","event10")
elements <- c("page","geoCountry","geoCity")

report.data <- QueueRanked(reportsuite.id, date.from, date.to, metrics, elements)

You may also wish to set any of the 6 optional named parameters. While you can specify more than one element with selected, at this point, the 1.4 API only supports this for the first element specified.

date.from <- "2014-01-01"
date.to <- "2013-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews","event10","event10")
elements <- c("page","geoCountry","geoCity")
top <- 100
start <- 100
selected <- list(page=c("Home","Search","About"))
segment.id <- "dw:12345"
data.current <- TRUE
expedite <- TRUE

report.data <- QueueRanked(reportsuite.id, date.from, date.to, metrics,elements,top=top,start=start,selected=selected,segment.id=segment.id,data.current=data.current,expedit=expedite)

QueueTrended

Returns a trended report. This is an ordered list of elements and associated metrics with time granularity.

QueueTrended requires a start and end date, a reportsuite ID, a character vector of elements and a character vector of metrics.

date.from <- "2014-01-01"
date.to <- "2014-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews","event10")
elements <- c("page","geoCountry","geoCity")

report.data <- QueueTrended(reportsuite.id, date.from, date.to, metrics, elements)

You may also wish to set any of the 7 optional named parameters. As with QueueRanked the 1.4 API only supports selected for the first element specified.

date.from <- "2014-01-01"
date.to <- "2013-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews","event10")
elements <- c("page","geoCountry","geoCity")
top <- 100
start <- 100
selected <- list(page=c("Home","Search","About"))
date.granularity <- "hour"
segment.id <- "dw:12345"
data.current <- TRUE
expedite <- TRUE

report.data <- QueueTrended(reportsuite.id, date.from, date.to, metrics,elements,top=top,start=start,selected=selected,segment.id=segment.id,data.current=data.current,expedit=expedite)

QueuePathing

Returns a pathing report. This is an ordered list of paths matching the specified pattern.

QueuePathing requires a start and end date, a reportsuite ID, a single element, a single metric and a pattern of element values that defined the path.

date.from <- "2014-01-01"
date.to <- "2014-01-07"
reportsuite.id <- "your_report_suite"
metric <- "pageviews"
element <- "page"
pattern <- c("Home",":::anything:::",":::anything:::")

report.data <- QueuePathing(reportsuite.id, date.from, date.to, metric, element, pattern)

QueueFallout

Returns a fallout report. This is a pathed list of elements, with fallout values for each.

QueuePathing requires a start and end date, a reportsuite ID, a single element, a character vector of metrics and a character vector of element values that defined the checkpoints.

date.from <- "2014-01-01"
date.to <- "2014-01-07"
reportsuite.id <- "your_report_suite"
metrics <- c("visits","uniquevisitors","pageviews","event10")
element <- "page"
checkpoints <- c("Home","Contact","ThankYou")

report.data <- QueuePathing(reportsuite.id, date.from, date.to, metrics, element, checkpoints)

Understanding the Available Data

Using the API, you can retrieve the setup of your report suite and view definitions for evars and sprops, success events, report suites and segments.

GetElements

Gets valid elements for a report suite for the current user. This list is restricted by optionally specified existing elements, existing metrics and date granularity.

elements.valid <- GetElements("your_report_suite",metrics=c('visitors','pageviews'),elements=c('page','geoCountry'),date.granularity='day')

GetMetrics

Gets valid metrics for a report suite for the current user. This list is restricted by optionally specified existing elements, existing metrics and date granularity.

metrics.valid <- GetMetrics("your_report_suite",metrics=c('visitors','pageviews'),elements=c('page','geoCountry'),date.granularity='day')

GetEvars

Gets evar (conversion variable) definitions for the specified report suite(s). Useful to audit or document a report suite or company in Adobe Analytics.

evars <- GetEvars(c("your_prod_report_suite","your_dev_reportsuite"))

GetProps

Gets sprop (traffic variable) definitions for the specified report suite(s). Useful to audit or document a report suite or company in Adobe Analytics.

props <- GetProps(c("your_prod_report_suite","your_dev_reportsuite"))

GetSuccessEvents

Gets success event definitions for the specified report suite(s). Useful to audit or document a report suite or company in Adobe Analytics.

successevents <- GetSuccessEvents(c("your_prod_report_suite","your_dev_reportsuite"))

GetReportSuites

Gets all report suites for the company.

reportsuites <- GetReportSuites()

GetSegments

Gets a list of segments for the specified report suites. Useful to find segment IDs for use in reporting helper functions or JSON report definitions.

segments <- GetSegments(c("your_prod_report_suite","your_dev_reportsuite"))

Debugging

If you put the library into debug mode, it will return more verbose output, and save some responses to disk so that they can be loaded in the console for debugging.

RAA_SetDebug(TRUE)