-
Notifications
You must be signed in to change notification settings - Fork 5
/
index.Rmd
193 lines (153 loc) · 7.95 KB
/
index.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
---
output:
github_document:
html_preview: false
---
```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
out.width = '100%',
fig.align = 'center',
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-")
```
[](https://travis-ci.org/StevenMMortimer/rdfp)
[](https://ci.appveyor.com/project/StevenMMortimer/rdfp)
[](https://cran.r-project.org/package=rdfp)
[](https://codecov.io/gh/StevenMMortimer/rdfp?branch=master)
<br>
<img src="man/figures/rdfp.png" width="120px" align="right" />
**Compiled using DFP API version: `v201905`**
**rdfp** allows you to use the DoubleClick for Publishers API from R (recently renamed
to Google Ad Manager). Manage inventory, create orders, pull reports, and more!
## Table of Contents
* [Installation](#installation)
* [Vignettes](#vignettes)
* [Usage](#usage)
* [Set API Version](#load-package-and-set-api-version)
* [Authenticate](#authenticate)
* [Get Current User Info](#get-current-user-info)
* [Pull a LineItem](#pull-a-lineitem)
* [Run a Report](#run-a-report)
* [Credits](#credits)
* [More Information](#more-information)
## Installation
```{r, eval = FALSE}
# install from CRAN
install.packages("rdfp")
# or get the latest version available on GitHub using the devtools package
# install.packages("devtools")
devtools::install_github("StevenMMortimer/rdfp")
```
If you encounter a clear bug, please file a minimal reproducible example on
[GitHub](https://github.com/StevenMMortimer/rdfp/issues).
## Vignettes
The README below outlines the package functionality, but review the vignettes for
more detailed examples on usage.
* [Administrative Tasks](articles/administrative-tasks.html)
* [Ad Trafficking Setup](articles/ad-trafficking-setup.html)
* [Manipulating Orders and LineItems](articles/manipulating-orders-and-lineitems.html)
* [Checking Availability](articles/checking-availability.html)
* [Pulling Reports](articles/pulling-reports.html)
## Usage
All functions start with `dfp_` so that you can easily identify DFP-specific
operations and use tab completion in RStudio. Most **rdfp** functions will
return a `tbl_df` or `list` parsed from the XML returned in the SOAP response.
### Load Package and Set API Version
Google releases 4 versions of the DFP API each year and deprecates versions older than
one year, so there is a lot that's regularly changing in this package. **rdfp**
is periodically compiled against a recent version of the API. If you would like
to use an older or newer API version that what is the package default, then just
specify it as an option.
```{r load-package}
library(rdfp)
# see the package default version
getOption("rdfp.version")
```
```{r set-version, eval=FALSE}
# this will force all calls to be against the version "v201902"
options(rdfp.version = "v201902")
```
### Authenticate
To authenticate you will first need to specify the `network_code` of the DFP instance
you would like to connect to. This is the only required option that the user must specify when
using the **rdfp** package. After setting the `network_code` all you need to do is
run `dfp_auth()`. If you already have a cached `.httr-oauth-rdfp` file in the current
working directory, then the token will be loaded and refreshed if necessary. Otherwise,
your browswer will pop open and you will interactively authenticate.
The package has other options like a client\_id and client\_secret where you can
connect using your own Google Client instead of the package default. Using your own
client requires you to first set one up in the
[Google Developers Console](https://console.developers.google.com).
```{r eval = FALSE}
options(rdfp.network_code = "12345678")
options(rdfp.application_name = "MyApp")
options(rdfp.client_id = "012345678901-99thisisatest99.apps.googleusercontent.com")
options(rdfp.client_secret = "Th1s1sMyC1ientS3cr3t")
# dfp_auth will use the options above and cache an OAuth token in the working directory
# the token will be refreshed when necessary
dfp_auth()
```
```{r auth, include = FALSE}
token_path <- here::here("tests", "testthat", "rdfp_token.rds")
suppressMessages(dfp_auth(token = token_path, verbose = FALSE))
options_path <- here::here("tests", "testthat", "rdfp_options.rds")
rdfp_options <- readRDS(options_path)
options(rdfp.network_code = rdfp_options$network_code)
```
### Get Current User Info
```{r administrative-example}
# Check current user or network
user_info <- dfp_getCurrentUser()
user_info[,c('id', 'isActive')]
network_info <- dfp_getCurrentNetwork()
network_info[,c('id', 'networkCode')]
```
#### Pull a LineItem
The function `dfp_getLineItemsByStatement()` function from the [LineItemService](https://developers.google.com/ad-manager/api/reference/v201905/LineItemService)
allows you to retrieve Line Items by Publishers Query Language (PQL) statement.
The statement is constructed as a list of lists that are nested to emulate the
hierarchy of the XML that needs to be created in the request.
```{r lineitem-example}
# Retrieve up to 3 Line Items that have a status of "DELIVERING"
request_data <- list('filterStatement'=list('query'="WHERE status='DELIVERING' LIMIT 3"))
resultset <- dfp_getLineItemsByStatement(request_data, as_df=TRUE)
resultset[,c('orderId', 'id', 'priority', 'deliveryRateType')]
```
### Run a Report
Below is an example of how to make a simple report request.
```{r report-example}
# In order to run a report you must specify how the report should be structured
# by specifying a reportQuery inside a reportJob. All of the dimensions, columns,
# date range options, etc. are documented at:
# https://developers.google.com/ad-manager/api/reference/v201905/ReportService.ReportQuery
request_data <- list(reportJob=list(reportQuery=list(dimensions='MONTH_AND_YEAR',
dimensions='AD_UNIT_ID',
adUnitView='FLAT',
columns = 'AD_SERVER_IMPRESSIONS',
columns = 'AD_SERVER_CLICKS',
dateRangeType='LAST_WEEK'
)))
# a convenience function has been provided to you to manage the report process workflow
# if you would like more control, see the example below which moves through each step in the process
report_data <- dfp_full_report_wrapper(request_data)
report_data[,c('Dimension.MONTH_AND_YEAR', 'Dimension.AD_UNIT_ID', 'Column.AD_SERVER_CLICKS')]
```
## Credits
This application uses other open source software components. The authentication
components are mostly verbatim copies of the routines established in the **googlesheets**
package (https://github.com/jennybc/googlesheets). We acknowledge and are grateful
to these developers for their contributions to open source.
## More Information
Google provides support for client libraries [here](https://developers.google.com/ad-manager/api/clients),
but unfortunately, R is not a supported language. Google's client libraries directly
reference the production WSDLs to interact with the API, but this package makes
SOAP requests best formatted to match the WSDL standards. This articulation is not
perfect and continued progress will be made to bring functionality up to par with
the client libraries.
Most all operations supported by the DFP API are available
via this package. It is strongly recommended that you use the
[DFP API Reference](https://developers.google.com/ad-manager/api/rel_notes)
when using this package. Details on formatting, attributes, and methods are all
better explained by Google's documentation.
[Top](#)