> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Chiến dịch Google Search

> Tạo chiến dịch Tìm kiếm trên Google Ads cùng ngân sách, từ khóa, văn bản quảng cáo và nhắm mục tiêu theo vị trí trong một yêu cầu

Tạo một chiến dịch Tìm kiếm trên Google Ads chỉ trong một yêu cầu. Ayrshare tạo đồng thời ngân sách, chiến dịch, một nhóm quảng cáo, các từ khóa của bạn, một quảng cáo tìm kiếm thích ứng và phần nhắm mục tiêu theo vị trí. Nếu Google từ chối bất kỳ phần nào, sẽ không có gì được tạo.

Yêu cầu dùng cấu trúc chung của [Chiến dịch Quảng cáo](https://www.ayrshare.com/docs/apis/ads/campaigns.md). Trang này trình bày những điểm dành riêng cho Google.

<ul>
  <li>Quảng cáo Google được bật theo từng tài khoản. Hãy liên hệ với chúng tôi để kích hoạt.</li>
  <li>Trước tiên, hãy liên kết Google Ads từ trang "Social Accounts". `accountId` là mã khách hàng Google Ads gồm 10 chữ số, có hoặc không có dấu gạch nối (`123-456-7890`).</li>
  <li>Người dùng Google mà bạn liên kết phải có quyền truy cập trực tiếp vào tài khoản quảng cáo. Các tài khoản bạn chỉ truy cập được thông qua một tài khoản người quản lý sẽ không được liệt kê và hiện chưa thể sử dụng: hãy thêm người dùng đó vào chính tài khoản quảng cáo. Các tài khoản người quản lý cũng không được liệt kê: chúng không thể chứa chiến dịch.</li>
  <li>Chiến dịch mới bắt đầu ở trạng thái `paused` trừ khi bạn gửi `status: "active"`.</li>
  <li>Ngân sách được tính theo ngày, bằng đơn vị tiền tệ của tài khoản quảng cáo. Không gửi `budget.currency`: trường này sẽ trả về `code: 101`.</li>
  <li>Chi tiêu bằng loại tiền khác được quy đổi sang USD để thanh toán theo tỷ giá của ngày đó từ Open Exchange Rates. Tài khoản dùng loại tiền không thể quy đổi sẽ trả về `code: 101` trước khi bất kỳ thứ gì được tạo.</li>
  <li>Quảng cáo chỉ hiển thị trên Google Search, không hiển thị trên các đối tác tìm kiếm hoặc Mạng Hiển thị (Display Network).</li>
</ul>

> [!NOTE]
>
> **Theo dõi chuyển đổi.** `maximizeConversions` chỉ hoạt động khi tính năng theo dõi chuyển đổi đã được thiết lập trong tài khoản Google Ads của bạn. Ayrshare không thiết lập tính năng này cho bạn. Nếu chưa có, hãy dùng `maximizeClicks` hoặc `manualCpc`.

## Tham số Header

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

**Idempotency-Key** `string` *required*

Một giá trị duy nhất mới, chẳng hạn một UUID, cho mỗi chiến dịch mới. Lặp lại một yêu cầu với cùng khóa sẽ trả về phản hồi đầu tiên và không tạo thêm gì mới. Khi một yêu cầu tạo thất bại trước khi Ayrshare gửi chiến dịch đến Google, khóa sẽ được giải phóng, vì vậy bạn có thể sửa yêu cầu và thử lại với cùng khóa đó. Điều này áp dụng cho một giá trị bị Ayrshare từ chối (chẳng hạn một chiến lược đặt giá thầu không được hỗ trợ), một tài khoản dùng loại tiền không thể quy đổi sang USD, và mọi lỗi trong bước kiểm tra tài khoản mà Ayrshare thực hiện trước, kể cả khi Google từ chối. Một yêu cầu tạo thất bại sau khi chiến dịch đã được gửi đến Google sẽ giữ nguyên phản hồi của nó: hãy thử lại với một khóa mới.

## Tham số Body

Các trường chung hoạt động như mô tả trên trang [Chiến dịch Quảng cáo](https://www.ayrshare.com/docs/apis/ads/campaigns.md). Trên Google:

**type** `string` *required*

`search`.

**bidding.strategy** `string` *required*

`maximizeClicks`, `manualCpc`, hoặc `maximizeConversions`. Bất kỳ giá trị nào khác sẽ trả về `code: 101`.

**euPoliticalAdvertising** `boolean` *required*

Google yêu cầu khai báo này trên mọi chiến dịch. Khi còn bất kỳ chiến dịch nào trong một tài khoản chưa được khai báo, Google sẽ từ chối mọi thay đổi đối với các chiến dịch của tài khoản đó.

**schedule** `object`

Google lên lịch theo trọn ngày, theo múi giờ của tài khoản quảng cáo. `start` bắt đầu lúc 00:00:00 của ngày đó và `end` dừng lúc 23:59:59 của ngày đó; thời gian bạn gửi chỉ dùng để chọn ngày. `start` có thể là hôm nay nhưng không được là một ngày trước đó. Với chiến dịch kéo dài một ngày, hãy gửi cùng một ngày cho `start` và `end`. Một `end` rơi vào ngày sớm hơn `start` sẽ trả về `code: 101`.

**targeting** `object`

Google ghép quảng cáo Tìm kiếm với người dùng dựa trên ngôn ngữ của văn bản quảng cáo, vì vậy không có tùy chọn cài đặt ngôn ngữ. Gửi `targeting.languages` sẽ trả về `code: 101`.

**thuộc tính**

**locations** `string[]`

Các id vị trí của Google, ví dụ `2840` cho Hoa Kỳ. Tìm id trong [danh sách mục tiêu địa lý](https://developers.google.com/google-ads/api/data/geotargets) của Google. Bỏ qua trường này để nhắm mục tiêu mọi vị trí.

**platformOptions.google** `object` *required*

**thuộc tính**

**finalUrl** `string` *required*

Trang `http` hoặc `https` mà quảng cáo mở ra.

**headlines** `string[]` *required*

Từ 3 đến 15 dòng tiêu đề, mỗi dòng tối đa 30 ký tự.

**descriptions** `string[]` *required*

Từ 2 đến 4 nội dung mô tả, mỗi nội dung tối đa 90 ký tự.

**path1** `string`

Phần đầu tiên của đường dẫn hiển thị sau tên miền, tối đa 15 ký tự.

**path2** `string`

Phần thứ hai của đường dẫn hiển thị, tối đa 15 ký tự. Cần có `path1`.

**keywords** `object[]` *required*

Ít nhất một từ khóa: `{ "text": string, "matchType": "exact" | "phrase" | "broad" }`. `text` tối đa 80 ký tự và 10 từ.

**maxCpc** `number`

Số tiền tối đa trả cho mỗi lượt nhấp, bằng đơn vị tiền tệ của tài khoản. Bắt buộc với `manualCpc`. Với `maximizeClicks`, trường này giới hạn mỗi giá thầu. Không được chấp nhận với `maximizeConversions`.

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}'
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/google/campaigns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
  },
  body: JSON.stringify({
    "accountId": "123-456-7890",
    "name": "Fall sale",
    "type": "search",
    "budget": { "amount": 25, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "targeting": { "locations": ["2840"] },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/fall-sale",
        "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "path1": "shoes",
        "keywords": [
          { "text": "running shoes", "matchType": "phrase" },
          { "text": "trail running shoes", "matchType": "exact" }
        ]
      }
    }
  })
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {
    "Authorization": "Bearer API_KEY",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10",
}

payload = {
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": False,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}

r = requests.post("https://api.ayrshare.com/api/ads/google/campaigns", headers=headers, json=payload)

print(r.json())
```

```php PHP theme={"system"}
<?php
$payload = <<<'JSON'
{
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}
JSON;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ayrshare.com/api/ads/google/campaigns",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error: " . $err;
} else {
    echo $response;
}
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
        client.DefaultRequestHeaders.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10");

        var payload = """
            {
              "accountId": "123-456-7890",
              "name": "Fall sale",
              "type": "search",
              "budget": { "amount": 25, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "targeting": { "locations": ["2840"] },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/fall-sale",
                  "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "path1": "shoes",
                  "keywords": [
                    { "text": "running shoes", "matchType": "phrase" },
                    { "text": "trail running shoes", "matchType": "exact" }
                  ]
                }
              }
            }
            """;

        var response = await client.PostAsync(
            "https://api.ayrshare.com/api/ads/google/campaigns",
            new StringContent(payload, Encoding.UTF8, "application/json"));
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := `{
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}`

    req, _ := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/google/campaigns", strings.NewReader(payload))
    req.Header.Add("Authorization", "Bearer API_KEY")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateCampaign {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "accountId": "123-456-7890",
              "name": "Fall sale",
              "type": "search",
              "budget": { "amount": 25, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "targeting": { "locations": ["2840"] },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/fall-sale",
                  "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "path1": "shoes",
                  "keywords": [
                    { "text": "running shoes", "matchType": "phrase" },
                    { "text": "trail running shoes", "matchType": "exact" }
                  ]
                }
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/campaigns"))
            .header("Authorization", "Bearer API_KEY")
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'uri'

uri = URI.parse('https://api.ayrshare.com/api/ads/google/campaigns')

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer API_KEY'
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = '6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10'
request.body = <<~JSON
  {
    "accountId": "123-456-7890",
    "name": "Fall sale",
    "type": "search",
    "budget": { "amount": 25, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "targeting": { "locations": ["2840"] },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/fall-sale",
        "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "path1": "shoes",
        "keywords": [
          { "text": "running shoes", "matchType": "phrase" },
          { "text": "trail running shoes", "matchType": "exact" }
        ]
      }
    }
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

```json 200: Campaign Created theme={"system"}
{
  "status": "success",
  "platform": "google",
  "campaignId": "21534567890",
  "adGroupId": "16812345678",
  "adId": "71234567890",
  "campaignStatus": "paused"
}
```

```json 400: Too Few Headlines theme={"system"}
{
  "action": "request",
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
  "details": "platformOptions.google.headlines: Supply at least 3 headlines."
}
```

## Lỗi

| Mã | Khi nào |
| - | - |
| `101` | Một trường bị thiếu hoặc không hợp lệ. `details` cho biết đó là trường nào. |
| `205` | Google đã từ chối yêu cầu: ví dụ, tài khoản đã có một chiến dịch với tên này, hoặc văn bản quảng cáo vi phạm chính sách quảng cáo của Google. `details` cho biết cần thay đổi gì. |
| `400` | Người dùng Google mà bạn liên kết không thể truy cập tài khoản quảng cáo này, quyền truy cập Google Ads đã bị thu hồi, chiến dịch không thuộc về bạn, hoặc một thay đổi nhắm đến chiến dịch đã bị xóa trong Google Ads. |
| `370` | Google không thể hoàn tất yêu cầu, hoặc Google chưa phê duyệt quyền truy cập của Ayrshare. `details` bao gồm id yêu cầu của Google nếu có. Một yêu cầu tạo trả về `370` do phản hồi của Google bị mất vẫn có thể đã tạo chiến dịch. Google từ chối chiến dịch thứ hai có cùng tên trong một tài khoản, vì vậy việc thử lại với cùng `name` sẽ trả về `205` thay vì tạo bản trùng lặp. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.