Adapty CLI, adapty asa konusu altında Ads Manager hesabınızı terminalden yönetebilir. Kampanyalar, reklam grupları, anahtar kelimeler, reklamlar, ürün sayfaları, otomasyon kuralları, metrikler ve rakip araştırmalarını kapsar.

Bir tarayıcıyı yavaşlatan işler için kullanın: bir yapay zeka ajanına reklam performansınıza canlı erişim vermek, bir dosyadan birkaç yüz anahtar kelime eklemek ve aynı kurulumu birkaç kampanyada çalıştırmak. Diğer her şey için kontrol paneli daha hızlı kalır.

Başlamadan önce

Ads Manager komutları, CLI’nin geri kalanıyla aynı kurulum ve oturum açma bilgilerini kullanır. Henüz bunu yapmadıysanız, hızlı başlangıç kılavuzunun 1. ve 2. adımlarını izleyin.

Ön Koşullar

Her adapty asa komutu için iki ek koşul geçerlidir:

• Bağlı bir Apple Ads hesabı: adapty asa connect komutuyla veya kontrol panelinde Adapty Ads Manager’ı kullanmaya başlama bölümünde açıklandığı şekilde bağlayın.
• Aktif bir Ads Manager aboneliği: Abonelik olmadan her komut 402 ads_manager_subscription_required hatasıyla başarısız olur.

İkisini birden raporlayan komut:

adapty asa whoami

CLI’nin Geri Kalanından Farkları

• --app bayrağı yoktur: Kapsam, token’ınızın ait olduğu şirkettir. --app yalnızca bazı list komutlarında filtre olarak bulunur.
• Yazma işlemleri doğrudan Apple’a ulaşır: Hesabınızda değişiklik yapan her komut, göndermeden önce istek gövdesini yazdırır ve onay ister. Bir hazırlık (staging) adımı yoktur.
• Okumalar ucuz, yazmalar değil: list komutlarını ve --dry-run seçeneğini özgürce kullanın. Diğer her şeye geri alınamaz gözüyle bakın.

Bir komut dosyasında onay istemini atlamak için --yes parametresini kullanın. --json modunda veya bir pipe içinde, bir yazma komutu hiçbir zaman gelmeyecek bir yanıtı beklemek yerine reddeder; bu nedenle --yes burada zorunludur.

İhtiyacınız olan ID’leri bulun

Her komut UUID alır ve her UUID bir list komutundan gelir. Hiyerarşide aşağıya doğru ilerleyin:

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

Her okumayı bir filtre ile kapsamlandırın. Filtreler, yazdırılan sayfayı değil sorguyu daraltır; bu nedenle kapsamlı bir okuma ucuzken kapsamsız bir okuma tüm hesabı sayfa sayfa tarar. --ad-group belirtmeden kullanılan adapty asa keywords list, konudaki en geniş okumadır.

Bu listeler yalnızca meta veri döndürür. Performans rakamları asa metrics ile alınır.

Anahtar kelime önerileri alın

Araştırma yapmadan bir anahtar kelime listesi oluşturmak için uygulamanıza özel hazır bir havuz edinin. adapty asa apps list komutundan aldığınız uygulamanın adam_id’sini ve havuz türünü — brand, generic veya competitor — girin:

adapty asa keywords recommend --adam-id <adam-id> --type generic --country US

Havuzun teklif veya eşleşme türü yoktur. Bunları kendiniz seçin, ardından Toplu anahtar kelime ekleme bölümünde açıklandığı gibi anahtar kelimeleri ekleyin. Çıktıda status: building görünüyorsa yaklaşık bir dakika sonra tekrar deneyin. Havuz türleri ve sınırları için Ads Manager komutlarına bakın.

Toplu anahtar kelime ekleme

Anahtar kelimeleri tek tek eklemek, kontrol panelini kullanmak zorunda kalmanın başlıca nedenidir. Her satıra bir anahtar kelime gelecek şekilde bir metin dosyası oluşturun:

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

Anahtar kelimeler, çağrı başına en fazla 100’lük gruplar hâlinde uygulanır. Daha büyük listeleri birden fazla çağrıya bölün.

İki tür hata mümkündür ve bunlar farklı davranır. Geçersiz bir ID, Apple çağrılmadan önce tüm toplu işlemi başarısız kılar; dolayısıyla hiçbir şey uygulanmaz. Apple ise bazı anahtar kelimeleri tek tek reddedebilir — geri kalanlar yine de eklenir ve her red, gerekçesiyle birlikte raporlanır. Yalnızca çıkış koduna değil, özet satırına da bakın.

Tam bir dosya göndermeden önce birkaç anahtar kelimeyle başlayıp sonucu kontrol edin.

Maksimum Dönüşüm kampanyası oluşturma

MAX_CONVERSIONS ile teklif veren bir kampanya, yalnızca otomatik bir reklam grubuna sahip olduğunda yayınlanır; bu nedenle ikisini birlikte oluşturun:

adapty asa campaigns create --org <campaign-group-id> --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS
adapty asa ad-groups create --campaign <campaign-id> --name "Automated Max Conv" --automated

O reklam grubu oluşturulana kadar kampanya serving_status: NOT_RUNNING bildirir; serving_state_reasons alanında AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING yer alır ve campaigns create hem nedeni hem de bunu çözen komutu yazdırır.

--automated seçeneği bu gereksinimi karşılayan şeydir — --automated-keywords ile oluşturulan normal bir reklam grubu bunu karşılamaz. Apple, otomatik reklam grubunu kendisi zamanlar ve yönetir; bu nedenle --start-time almaz, --default-bid isteğe bağlıdır ve reklam grubu etkin kalır: harcamayı durdurmak için kampanyayı duraklatın.

Kampanyada --target-cpa değerini --daily-budget değerinden düşük tutun.

Kredi limiti için Faturalama Seçeneklerini Ayarlama

Apple, kredi limitiyle faturalandırılan bir kuruluştaki her kampanya için Faturalama Seçeneklerini zorunlu kılar. adapty asa orgs list komutu, her kuruluşun payment_model değerini raporlar — LOC değeri, beş --invoice-* bayrağının geçerli olduğu anlamına gelir:

adapty asa campaigns create --org <campaign-group-id> --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com

Pass all five in one call — a partial set is rejected before the request reaches Apple. Without them, the campaign is created but reports serving_status: NOT_RUNNING with MISSING_BO_OR_INVOICING_FIELDS.

Beş bayrağın tamamını tek bir çağrıda geçin; eksik set Apple’a ulaşmadan reddedilir. Bunlar olmadan kampanya oluşturulur ancak serving_status: NOT_RUNNING ile birlikte MISSING_BO_OR_INVOICING_FIELDS hatası döner.

The same five flags on adapty asa campaigns update set the Invoicing Options on a campaign that already exists. They replace the stored set as a whole, so pass all five even to change one of them.

adapty asa campaigns update komutundaki aynı beş bayrak, mevcut bir kampanyada Faturalama Seçeneklerini ayarlar. Depolanan kümenin tamamının yerini aldıklarından, yalnızca birini değiştirmek istediğinizde bile beşini birden geçin.

Tek işlemde kampanya yapısı oluşturma

campaigns bulk-create, campaigns create ve ad-groups create üzerinde döngü kuran bir betiğin yerini alır. Kampanyaları, reklam gruplarını, anahtar kelimeleri, negatif anahtar kelimeleri ve reklamları tek bir işlem olarak gönderir:

adapty asa campaigns bulk-create --file structure.json

Girdi, yapının JSON açıklamasıdır — alanlar için yapı formatına bakın. JSON, bir AI ajanı için en doğal yoldur: yapıyı oluşturur ve doğrudan aktarır:

cat structure.json | adapty asa campaigns bulk-create --file -

Yerel bir Apple Ads toplu şablonu da giriş olarak kullanılabilir — sunucu, Campaign_And_Adgroup_Template.xlsx dosyasını veya bir anahtar kelime .csv dosyasını yapıya dönüştürür. --org-id, adapty asa orgs list komutundan alınan sayısal org_id değerini alır. Oluşturma işleminden önce dönüşümü incelemek için --preview ekleyin:

adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567 --preview

Dönüşüm sorunları, ait oldukları sayfa, satır ve sütunla birlikte raporlanır. Çıktı yapısı doğru göründüğünde, göndermek için --preview parametresini kaldırın.

--preview çıktısı aynı zamanda başlangıç yapı dosyası oluşturmanın en hızlı yoludur: çıktıyı kaydedin, düzenleyin ve --file ile gönderin — tıpkı automations get komutunun bir kural şablonu sağlaması gibi.

Yapının tamamı herhangi bir şey oluşturulmadan önce doğrulanır; reddedilmesi durumunda geçersiz her düğüm listelenir. Kabul edildikten sonra nesneler sunucuda oluşturulurken komut ilerlemeyi raporlar. Nihai rapor success, partial veya failed şeklindedir — partial sonucu, oluşturulmayan her nesneyi Apple’ın hatasıyla birlikte listeler.

Büyük bir yapı için, işlem kimliğini hemen geri almak ve ilerlemeyi daha sonra okumak amacıyla --no-wait seçeneğini kullanın:

adapty asa campaigns bulk-status <operation-id>

Ajanlar ve betiklerden metrikleri sorgulama

asa metrics, belirli bir tarih aralığında hesabın herhangi bir düzeyinde rapor oluşturur. Sonucu bir yapay zeka ajanının veya betiğin doğrudan işleyebilmesi için --json ekleyin:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric zorunludur ve tekrarlanabilir; Ads Manager’ın takip ettiği metrik adlarını alır. Tam liste için Metrikler sayfasına bakın. Adını belirttiğiniz her metrik, sayfa kesilmeden önce tüm varlık düzeyinde hesaplanır; bu nedenle tüm kataloğu istemek yerine yalnızca kullanacağınız sütunları isteyin.

--app, --campaign ve --ad-group seçenekleri raporu daraltır; bunu yapmak, bir çağrıyı hızlandırmanın en ucuz yoludur; çünkü maliyet, sayfa boyutundan değil toplanan varlık sayısından kaynaklanır. Dört metrik — subscribers, paid_subscribers, arppu ve arpas — her varlık düzeyinde benzersiz profilleri sayar ve bunlar herhangi bir varlık düzeyinde bir kampanya ya da reklam grubu filtresi gerektirir:

adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign <campaign-id> --json

Kohort metrikleri diğerlerinden farklı çalışır. ltv metriği yoktur; çünkü yaşam boyu değer bir tarihe göre değil, yenileme penceresine göre okunur. Bunun yerine pencereyi belirtin:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90 --order-by-day 90

Bu komut, kampanyalarınızı 90. gün ROAS değerine göre sıralar. Tek bir çağrıya en fazla 16 pencere sığar.

Her satır tek bir entity’yi temsil eder; sunucu tarafında zaten toplanmış ve sıralanmıştır. Dolayısıyla “harcamaya göre en iyi beş kampanya” sorusunu yanıtlamak için her sayfayı dolaşmak yerine tek bir çağrı yeterlidir:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

Metrikler ve arama terimleri listesi, şirket başına tek bir analitik bütçesini paylaşır: dakikada 5 çağrı, ve herhangi bir 10 saniyelik aralıkta en fazla 2. Sorguyu tekrar tekrar çağırmak yerine, hedefe yönelik tek bir soru sorun.

Bir rapora iki kap uygulanır. Raporlama dönemi, gruplama inceliğiyle sınırlandırılır — --group-by day ile 28 gün, dönem gruplaması olmaksızın 90 gün, haftaya göre 180, aya göre 365 — ve her sayfa, varlık × ülke × dönem başına bir satır hesaplanarak 5000 döküm satırıyla sınırlıdır. Bu nedenle raporu genişletmek için daha fazla çağrıya bölmek yerine --group-by seçeneğini kabalaştırın.

Rakip anahtar kelimeleri kontrol edin

Tek bir komutla, aynı anda en fazla beş App Store uygulamasının teklif verdiği anahtar kelimeleri görebilirsiniz:

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

Dönem ve ülkeler sunucu tarafında sabit tutulur — her ülke genelinde son tam ay — dolayısıyla komutun uygulama ID’lerinin ötesinde herhangi bir parametresi yoktur. Belirli bir uygulama kümesi için ilk çağrı onlarca saniye sürebilir.

Rakip anahtar kelime verilerini bir rapora düzenli aralıklarla çekmek için bunu kullanın. Sonuçları filtrelemek, ülkeleri yan yana karşılaştırmak veya bulduğunuz anahtar kelimeleri doğrudan bir kampanyaya eklemek için kontrol panelindeki Market Intelligence bölümünü kullanın.

Otomasyon kurallarını çalıştırma

CLI, verdiğiniz JSON’ı sakladığından, geçerli bir otomasyon kuralı dosyası almanın en hızlı yolu kontrol panelinde bir kural oluşturup ardından geri okumaktır:

adapty asa automations get <automation-id> --json > rule.json

Bu dosyayı düzenleyerek yeni kurallar için şablon olarak kullanın:

adapty asa automations create --file rule.json

Bir kural dosyası tam olarak bir koşul ve bir eylem içerir; API de kural başına bu kadarını saklar. Bir dosyayı automations update komutuna geçirmeden önce internal_id alanını kaldırın — bu alan mevcut olursa güncelleme reddedilir.

Bayraklardan Anahtar Kelime Olarak Ekle eylemi oluşturma

Tek istisna olan Anahtar Kelime Olarak Ekle eylemi, elle yazılan JSON’un dışında tutulur. Bir arama terimini tanıtan veya bir anahtar kelimeyi başka bir reklam grubuna kopyalayan bu eylem, hedef reklam gruplarını, teklifi ve eşleme türünü bayraklardan alır:

adapty asa automations create --file rule.json --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group

automations update üzerindeki aynı flag’ler, yanlış şekille kaydedilmiş bir kuralı onarır. CLI kuralı okur, action’ı sıfırdan yeniden oluşturur ve yalnızca Add as keyword action’ına uyan kayıtlı ayarları koruyarak geri yazar:

adapty asa automations update <automation-id> --target-ad-group <ad-group-id> --match-type EXACT --cpt-bid-type search_term_current_cpt

Eksik olan her şey bir flag’den gelmek zorundadır. Tam set için Ads Manager komutlarına bakın.

Teklife izin vermeden önce bir kuralı test edin:

adapty asa automations run <automation-id> --dry-run

Kuru çalıştırma, koşulları değerlendirir ve Apple Ads’e dokunmadan kuralın ne yapacağını günlüğe kaydeder. Çalıştırmalar hemen gerçekleştirilmek yerine sıraya alınır; bu nedenle komut bir çalıştırma ID’si yazdırır ve sonuç adapty asa automations runs içinde görünür.

Script’leri güvenle yeniden çalıştırma

Her yazma işlemi bir idempotency anahtarı gönderir. CLI, her çağrı için bir tane oluşturur ve ağ hatasından sonra bir kez yeniden dener; bu sayede iletim sırasında başarısız olan bir istek hiçbir zaman iki kez uygulanmaz.

Bir script içinde, tüm pipeline’ın yeniden çalıştırılabilmesi için anahtarı kendiniz sabitleyin:

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Aynı komutu 24 saat içinde tekrar çalıştırmak, kaydedilen sonucu döndürür ve ikinci bir kampanya oluşturmak yerine Already applied earlier mesajını yazdırır. Aynı key ile farklı bir body gönderilmesi 422 hatasıyla sonuçlanır; bu da key’i yanlışlıkla yeniden kullanan düzenlenmiş bir script’i yakalar.

Sırada ne var

• Apple Ads’i bir AI kodlama aracıyla yönetin — Claude Code, Copilot CLI, Codex veya Gemini CLI’nin bu komutları sizin yerinize çalıştırabilmesi için Apple Ads eklentisini yükleyin.
• Ads Manager komutları — argümanları, bayrakları ve kabul edilen değerleriyle birlikte tüm komutlar.
• Otomasyonlar — her kural türünün ne yaptığı ve hangi eylemleri gerçekleştirebileceği.
• Metrikler — --metric tarafından kabul edilen metrik adları ve her birinin nasıl hesaplandığı.