> ## 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.

# حملات بحث Google

> أنشئ حملة بحث Google Ads بميزانيتها وكلماتها المفتاحية ونص إعلانها واستهداف مواقعها في طلب واحد

أنشئ حملة بحث في Google Ads بطلب واحد. يُنشئ Ayrshare الميزانية والحملة ومجموعة إعلانية واحدة وكلماتك الرئيسية وإعلان بحث متجاوبًا واحدًا واستهداف المواقع معًا. وإذا رفض Google أي جزء منها، فلن يُنشأ أي شيء.

يستخدم الطلب البنية المشتركة الموضحة في [الحملات الإعلانية](https://www.ayrshare.com/docs/apis/ads/campaigns.md). تتناول هذه الصفحة ما يخص Google تحديدًا.

<ul>
  <li>تُفعَّل إعلانات Google لكل حساب على حدة. تواصل معنا لتفعيلها.</li>
  <li>اربط Google Ads من صفحة "Social Accounts" (الحسابات الاجتماعية) أولًا. `accountId` هو معرّف عميل Google Ads المكوّن من 10 أرقام، مع الشرطات أو بدونها (`123-456-7890`).</li>
  <li>يجب أن يكون لمستخدم Google الذي تربطه وصول مباشر إلى حساب الإعلانات. الحسابات التي لا تصل إليها إلا عبر حساب مدير لا تظهر في القائمة ولا يمكن استخدامها بعد: أضف ذلك المستخدم إلى حساب الإعلانات نفسه. ولا تظهر حسابات المدير في القائمة أيضًا: فهي لا يمكن أن تحتوي على حملات.</li>
  <li>تبدأ الحملات الجديدة بالحالة `paused` ما لم ترسل `status: "active"`.</li>
  <li>الميزانية يومية، بعملة حساب الإعلانات. لا ترسل `budget.currency`: إذ يُعيد ذلك `code: 101`.</li>
  <li>يُحوَّل الإنفاق بعملة أخرى إلى الدولار الأمريكي (USD) لأغراض الفوترة بسعر صرف ذلك اليوم من Open Exchange Rates. يُعيد الحساب بعملة لا يمكن تحويلها `code: 101` قبل إنشاء أي شيء.</li>
  <li>تظهر الإعلانات على Google Search فقط، وليس على شركاء البحث أو على Display Network (شبكة الإعلانات الصورية).</li>
</ul>

> [!NOTE]
>
> **تتبّع الإحالات الناجحة.** لا يعمل `maximizeConversions` إلا عند إعداد تتبّع الإحالات الناجحة في حساب Google Ads الخاص بك. لا يتولى Ayrshare إعداده نيابةً عنك. وبدونه، استخدم `maximizeClicks` أو `manualCpc`.

## معاملات الترويسة

**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*

قيمة فريدة جديدة، مثل UUID، لكل حملة جديدة. يؤدي تكرار طلب بالمفتاح نفسه إلى إعادة الاستجابة الأولى دون إنشاء أي شيء جديد. عندما يفشل الإنشاء قبل أن يرسل Ayrshare الحملة إلى Google، يُحرَّر المفتاح، فيمكنك تصحيح الطلب وإعادة المحاولة بالمفتاح نفسه. يشمل ذلك قيمة يرفضها Ayrshare (مثل استراتيجية عروض أسعار غير مدعومة)، والحساب بعملة لا يمكن تحويلها إلى الدولار الأمريكي، وأي فشل في التحقق من الحساب الذي يجريه Ayrshare أولًا، بما في ذلك رفض Google له. أما الإنشاء الذي يفشل بعد إرسال الحملة إلى Google فيحتفظ بإجابته: أعد المحاولة بمفتاح جديد.

## معاملات الجسم

تعمل الحقول المشتركة كما هو موضح في [الحملات الإعلانية](https://www.ayrshare.com/docs/apis/ads/campaigns.md). على Google:

**type** `string` *required*

`search`.

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

`maximizeClicks` أو `manualCpc` أو `maximizeConversions`. تُعيد أي قيمة أخرى `code: 101`.

**euPoliticalAdvertising** `boolean` *required*

يشترط Google هذا الإقرار في كل حملة. وطالما توجد في الحساب أي حملة بلا إقرار، يرفض Google كل تغيير على حملات ذلك الحساب.

**schedule** `object`

يجدول Google أيامًا كاملة وفق المنطقة الزمنية لحساب الإعلانات. يبدأ `start` عند 00:00:00 من يومه، ويتوقف `end` عند 23:59:59 من يومه؛ والوقت الذي ترسله لا يحدد سوى اليوم. يمكن أن يكون `start` اليوم، لكن لا يمكن أن يكون يومًا سابقًا. لحملة مدتها يوم واحد، أرسل التاريخ نفسه في `start` و`end`. ويُعيد `end` في يوم أسبق من `start` القيمة `code: 101`.

**targeting** `object`

يطابق Google إعلانات البحث مع الأشخاص وفق لغة نص إعلانك، لذا لا يوجد إعداد للغة. يؤدي إرسال `targeting.languages` إلى إعادة `code: 101`.

**السمات الفرعية**

**locations** `string[]`

معرّفات مواقع Google، على سبيل المثال `2840` للولايات المتحدة. ابحث عن المعرّفات في [قائمة الأهداف الجغرافية](https://developers.google.com/google-ads/api/data/geotargets) من Google. لا ترسل هذا الحقل لاستهداف جميع المواقع.

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

**السمات الفرعية**

**finalUrl** `string` *required*

صفحة `http` أو `https` التي يفتحها الإعلان.

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

من 3 إلى 15 عنوانًا، لا يتجاوز كل منها 30 حرفًا.

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

من 2 إلى 4 أوصاف، لا يتجاوز كل منها 90 حرفًا.

**path1** `string`

الجزء الأول من مسار العرض الذي يظهر بعد النطاق، بحد أقصى 15 حرفًا.

**path2** `string`

الجزء الثاني من مسار العرض، بحد أقصى 15 حرفًا. يتطلب `path1`.

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

كلمة رئيسية واحدة على الأقل: `{ "text": string, "matchType": "exact" | "phrase" | "broad" }`. لا يتجاوز طول `text` 80 حرفًا و10 كلمات.

**maxCpc** `number`

أقصى مبلغ يُدفع مقابل النقرة، بعملة الحساب. مطلوب مع `manualCpc`. ومع `maximizeClicks` يضع حدًا أقصى لكل عرض سعر. غير مقبول مع `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."
}
```

## الأخطاء

| الرمز | متى |
| - | - |
| `101` | حقل مفقود أو غير صالح. يذكر `details` اسمه. |
| `205` | رفض Google الطلب: على سبيل المثال، يحتوي الحساب بالفعل على حملة بهذا الاسم، أو يخالف نص الإعلان سياسات Google الإعلانية. يوضح `details` ما يجب تغييره. |
| `400` | لا يستطيع مستخدم Google الذي ربطته الوصول إلى حساب الإعلانات هذا، أو أُلغي الوصول إلى Google Ads، أو الحملة لا تخصك، أو يستهدف التغيير حملة أُزيلت في Google Ads. |
| `370` | تعذّر على Google إكمال الطلب، أو لم يوافق Google بعد على وصول Ayrshare. يتضمن `details` معرّف طلب Google عند توفره. قد يكون طلب الإنشاء الذي يُعيد `370` بسبب فقدان رد Google قد أنشأ الحملة بالفعل. يرفض Google وجود حملة ثانية بالاسم نفسه في حساب واحد، لذا فإن إعادة المحاولة بالقيمة نفسها لـ `name` تُعيد `205` بدلًا من إنشاء حملة مكررة. |


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