Google Ads API Nodejs Client Library
## Usage
### Authentication
```ts
import { UserRefreshClient, JWT } from 'google-auth-library';
// for web application
const authClient = new UserRefreshClient({
clientId: '',
clientSecret: '',
refreshToken: '',
});
// or use JWT for service account
const authClient = new JWT({
keyFile: '',
subject: '',
scopes: ['https://www.googleapis.com/auth/adwords'],
});
```
### Customer
```ts
import { Customer } from '@htdangkhoa/google-ads';
const service = new Customer({
auth: authClient,
developer_token: '',
});
const { resource_names: customers } = await service.listAccessibleCustomers();
// ...
```
### Search
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
},
{
customer_id: '',
},
);
const customerClients = await service.search({
query: `
SELECT
customer_client.descriptive_name,
customer_client.resource_name,
customer_client.client_customer,
customer_client.level,
customer_client.manager
FROM customer_client
`,
});
// ...
```
### Search stream
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
}, {
customer_id: '',
}
);
const response = service
.setCustomerId('') // you can switch customer id
.setLoginCustomerId('')
.searchStream({
query: `
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
`,
});
for await (const { results } of response) {
// ...
}
```
### Campaign
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
},
{
customer_id: '',
login_customer_id: '',
},
);
const campaigns = await service.search({
query: `
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
`,
});
// ...
```
### Mutate
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
},
{
customer_id: '',
login_customer_id: '',
},
);
const response = await service.mutate({
mutate_operations: [
{
campaign_operation: {
create: {
// ...
},
update: {
// ...
},
remove: '',
},
},
],
partial_failure: true,
});
// ...
```
### Query Builder
```ts
import { QueryBuilder } from '@htdangkhoa/google-ads';
const query = new QueryBuilder()
.select(
'campaign.id',
'campaign.name',
'segments.device',
'metrics.clicks',
)
.from('campaign')
.where(
{
attribute: 'metrics.impressions',
operator: Operators.GREATER_THAN,
value: "0",
},
{
attribute: 'segments.device',
operator: Operators.EQUALS,
value: "MOBILE",
},
{
attribute: 'segments.date',
operator: Operators.DURING,
value: Functions.LAST_30_DAYS,
},
)
.orderBy(
{
attribute: 'metrics.clicks',
direction: Order.DESC,
},
)
.limit(10)
.build();
const response = await service.search({ query });
```
## Logging
Requests are logged with a one line summary and the full request/response body and headers.
| Log type | Log name | Success level | Failure level |
|----------|---------------------------------|---------------|---------------|
| SUMMARY | Google::Ads::GoogleAds::Summary | INFO | WARN |
| DETAIL | Google::Ads::GoogleAds::Detail | DEBUG | INFO |
### Basic
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
logging: true,
},
{
customer_id: '',
},
);
```
### Specific Log Type (SUMMARY or DETAIL)
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
logging: {
summary: true,
detail: false,
},
},
{
customer_id: '',
},
);
```
## gRPC Client Options
The `ServiceOptions` is extended from `@grpc/grpc-js` [ClientOptions](https://grpc.github.io/grpc/node/grpc.Client.html#~ClientOptions:~:text=to%20the%20server-,options,-Object), so you can pass any options you want to the client.
```ts
import { GoogleAds } from '@htdangkhoa/google-ads';
const service = new GoogleAds(
{
auth: authClient,
developer_token: '',
logging: {
summary: true,
detail: false,
},
interceptors: [
// your interceptors
],
},
{
customer_id: '',
},
);
```
## Interceptors
See more at [Node.js gRPC Library](https://grpc.github.io/grpc/node/module-src_client_interceptors.html) and some examples [here](https://github.com/grpc/proposal/blob/master/L5-node-client-interceptors.md).
## Development
### Prerequisites
- Protocol Buffer Compiler (protoc) version 3.0.0 or greater. The latest version can be downloaded from [here](https://grpc.io/docs/protoc-installation/)
- Node.js version 16 or greater (LTS recommended) and npm version 8 or greater. The latest version of Node.js can be downloaded from [here](https://nodejs.org/en/download/)
### Building
1. Install dependencies
```sh
yarn install
```
2. Pull in the new protos and compile them
```sh
yarn generate
# example
yarn generate v19
```
3. Make sure the version number in the `src` folder is correct (it should match the version number you passed to the `generate` command)
4. Run tests to make sure everything worked (you may need to update the version numbers here)
```sh
yarn test
```
5. Build the library
```sh
yarn build
```
6. Make a pull request, get it approved and merged into `main`
## License
The code in this project is released under the [MIT License](LICENSE).