---
title: "RAdwords Migration Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{radwords-migration-guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

### Migrate your R code from the Adwords API to the new Google Ads API with {**r4googleads**}

Over the past few years, Google has been developing a new API for its Google Ads services. On April 27, 2022, Google will shut down the current Adwords API. By the end of April, any R code that relies on our {**RAdwords**} package will be deprecated. To keep your code and data tasks running, you need to refactor your R code to be compatible with the new Google Ads API. We have created a new R package {**r4googleads**} that will replace our {**RAdwords**} package. {**r4googleads**} will give you the full functionality of {**RAdwords**} plus additional new features!

Start migrating your code now with our easy step-by-step guide!

## Installation

To install the latest stable version of {**r4googleads**} from R's official Comprehensive R Archive Network (CRAN) run

```{r,eval=FALSE,message=FALSE, warning=FALSE}
install.packages("r4googleads")
```

or install the latest development release from GitHub using the [{remotes}](https://CRAN.R-project.org/package=remotes) R package. 
(the below example code assumes the {remotes} package has been installed previously.)


```{r,eval=FALSE}
remotes::install_github("banboo-data/r4googleads")
```


## Authentication with the API

The authentication process of {**RAdwords**} and {**r4googleads**} remains the same (except for the function name). This means that you can easily use the {**r4googleads**} package with your existing {**RAdwords**} authentication objects (tokens). The good news is that you don't have to go through the whole authentication process and can just start code migration!

The previous {**RAdwords**} authentication:

```{r,eval=FALSE}
google_auth <- doAuth()
```

The {**r4googleads**} authentication now is:

```{r, eval=FALSE}
library(r4googleads)
google_auth <- authenticate()
```


## Loading Data

{**r4googleads**} allows you to apply the Google Ads Query Language directly. That is, you can write your own SQL-like syntax or use the [Query Builder] (https://developers.google.com/google-ads/api/fields/v9/overview_query_builder) provided by Google.

The previous {**RAdwords**} code:

```{r,eval=FALSE}
body <- statement(select = c('CampaignName', 'Clicks', 'Cost'),
                  report = "CAMPAIGN_PERFORMANCE_REPORT",
                  start = "2022-01-01",
                  end = "2022-01-10")
                  
data <- getData(clientCustomerId = 'XXX-XXX-XXXX', #use Adwords Account Id (MCC Id will not work)
                google_auth = google_auth,
                statement = body)

```

Loading data with {**r4googleads**}:

```{r,eval=FALSE}
sql_query <- "SELECT campaign.name, metrics.clicks, metrics.cost_micros
              FROM campaign
              WHERE segments.date BETWEEN '2022-01-01' AND '2022-01-10'
              AND metrics.impressions > 0
              PARAMETERS include_drafts=true"

query_service <- googleAdsSearch(
  aid = 'XXX-XXX-XXXX', # Google Ads Accountr ID
  query = sql_query,
  api_version = 'v9'
)

data <- query_google_ads(
  mcc_id = 'XXX-XXX-XXX', # Google Ads My Client Center ID
  google_auth = google_auth,
  service = query_service,
  raw_data = F
)

```

We provide you with a set of Google Ads SQL samples that you can load and explore using the following function commands:`default_search()`, `campaign_sample()`, `adgroup_sample()`, `adgroup_sample_1()`, `hotel_ads_sample()`, `keyword_sample()`, , `keyword_sample_1()`, `keyword_sample_2()`


## Exploring the API

With {**RAdwords**} you can explore the report types of the Adwords API using the `reports()` and `metrics()` methods.
In {**r4googleads**} you can explore the available [Google Ads API reports](https://developers.google.com/google-ads/api/fields/v9/overview) with the following code:

```{r,eval=FALSE}
tbl_schema_service = googleAdsFields(tbl = "campaign", api_version = 'v9')

tbl_schema <- query_google_ads(
  mcc_id = 'XXX-XXX-XXXX',
  google_auth = tbl_schema_service,
  service = my_service_2,
  raw_data = F
)

```

## Overview of functions and methods

The following table provides an overview of the new methods and their corresponding predecessor functions.

| Functionality     | {RAdwords}                  | {r4googleads}          |
|:------------------|:---------------------------:|-----------------------:|
| Authentication    | `doAuth()`                  | `authenticate()`       |
| Define Query      | `statement()`               | `googleAdsSearch()`    |
| Loading Data      | `getData()`                 | `query_google_ads()`   |
| Reports & Metrics | `reports()`; `metrics()`    | `googleAdsFields()`    |

## Metrics Names

In {**r4googleads**} we follow the metric naming convention of the Google Ads API. The metric names in the Google Ads API may be different from the names in the Adwords API. This means that you will either need to adjust the names in your existing data schema to match the metric names from the Google Ads API report results, or rename the results data frame names to match your existing data schema. For example, `clicks` becomes `metric.clicks` or `campaign` becomes `campaign.name`.
