Pubblicità

L'API Pubblicità ti consente di creare e gestire programmaticamente la pubblicità su Roblox. Copre due tipi di pubblicità:

• Pubblicità esperienziale — campagne di coinvolgimento che portano i giocatori alle tue esperienze, tramite l'Ads API.
• Pubblicità di articoli — sponsorizzazione di articoli del Marketplace per aumentarne la visibilità.

Prima di utilizzare l'Ads API, genera una chiave API e concedi accesso agli ambiti ad.campaign:read, ad.campaign:write e ad.billing:read. Includi la chiave nell'intestazione della richiesta x-api-key in ogni richiesta. Tutti gli endpoint dell'Ads API sono serviti da https://apis.roblox.com/ads-management/v1.`.

Concetti chiave

• Stato vs. stato di consegna — ogni campagna ha uno stato di ciclo di vita status che controlli (ACTIVE, PAUSED o CANCELLED, che è permanente) e uno deliveryStatus derivato, di sola lettura (IN_REVIEW, SERVING, NOT_SERVING o REJECTED). Una nuova campagna ha status ACTIVE e deliveryStatus IN_REVIEW fino al completamento della revisione della politica pubblicitaria. Quando una campagna non è in corso, leggi deliveryStatusReasons per il motivo.
• Il denaro è rappresentato come stringhe micro-USD — gli importi del budget sono stringhe decimali in micro-USD ("5000000" = $5.00), inviati e restituiti come stringhe per preservare la precisione. Dividi per 1.000.000 per convertire in dollari.
• Obiettivo — solo ENGAGEMENT (portare visite alla tua esperienza) è disponibile in v1.
• Creativi — le campagne utilizzano asset immagine di Open Cloud come creativi. Carica un'immagine tramite l'Assets API, quindi fai riferimento al suo ID asset in creativeAssetIds.
• Modifiche al budget — un aumento del budget si applica immediatamente; una diminuzione su una campagna in corso entra in vigore alla prossima mezzanotte nel fuso orario del conto di fatturazione.
• Versioning — la versione principale è nel percorso (/ads-management/v1). Le modifiche additive e retrocompatibili vengono fornite come versioni minori selezionate con l'intestazione X-Roblox-Api-Version; il baseline congelato 1.0 è il valore predefinito.

Pubblicità esperienziale

Il primo passo in una campagna di pubblicità esperienziale è scegliere l'esperienza da pubblicizzare. Elenca le esperienze che l'account può pubblicizzare, quindi recupera le opzioni della campagna (obiettivi, tipi di pagamento e dimensioni di targeting) e l'idoneità per quella che scegli.

1. Copia la chiave API nell'intestazione della richiesta x-api-key.
2. Invia una richiesta a advertisable-universes per elencare le esperienze che puoi pubblicizzare.
3. Invia una richiesta a campaign-options, sostituendo ${UniverseId} con l'ID dell'universo dell'esperienza target, per confermare l'idoneità e leggere i valori validi.

curl --location 'https://apis.roblox.com/ads-management/v1/advertisable-universes' \
--header 'x-api-key: ${ApiKey}'

curl --location 'https://apis.roblox.com/ads-management/v1/campaign-options?universeId=${UniverseId}' \
--header 'x-api-key: ${ApiKey}'

Se l'esperienza non è idonea, campaign-options restituisce un motivo di idoneità come NO_PERMISSION (l'account non può pubblicizzare l'esperienza) o BLOCKED (l'esperienza non è idonea per la pubblicità).

Crea una campagna

Invia un POST a campaigns con l'esperienza, gli ID degli asset creativi, il budget e il programma.

1. Carica la tua immagine creativa tramite l'Assets API e annota il suo ID asset.
2. Imposta l'intestazione x-idempotency-key su un UUID. Ripetere la stessa chiave con un corpo identico entro 24 ore restituisce la campagna originale invece di crearne una duplicata.
3. Imposta targetUniverseId, creativeAssetIds, budget e schedule nel corpo della richiesta.
4. Invia la richiesta.

curl --location 'https://apis.roblox.com/ads-management/v1/campaigns' \
--header 'x-api-key: ${ApiKey}' \
--header 'x-idempotency-key: ${UUID}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Promo estiva",
    "objective": "ENGAGEMENT",
    "paymentType": "CREDIT_CARD",
    "targetUniverseId": "${UniverseId}",
    "creativeAssetIds": ["${AssetId}"],
    "budget": { "type": "DAILY", "amountMicros": "5000000" },
    "schedule": { "startTime": "2026-08-01T00:00:00Z", "durationInDays": 7 }
}'

In caso di successo, la campagna viene restituita con status ACTIVE e deliveryStatus IN_REVIEW. A questo punto, è in coda per la revisione della politica pubblicitaria e non è ancora in corso:

{
  "id": "1122334455",
  "name": "Promo estiva",
  "objective": "ENGAGEMENT",
  "paymentType": "CREDIT_CARD",
  "targetUniverseId": "1234567890",
  "creativeAssetIds": ["9876543210"],
  "budget": { "type": "DAILY", "amountMicros": "5000000" },
  "schedule": { "startTime": "2026-08-01T00:00:00Z", "durationInDays": 7 },
  "status": "ACTIVE",
  "deliveryStatus": "IN_REVIEW",
  "createTime": "2026-07-27T00:00:00Z",
  "updateTime": "2026-07-27T00:00:00Z"
}

Campi del corpo della richiesta

Targeting

targeting è facoltativo; omettilo o invia un oggetto vuoto per raggiungere tutti i pubblici. Ogni dimensione è un array. Un array vuoto significa "tutti" per quella dimensione.

Controlla se una campagna è in corso

Dopo aver creato una campagna, controlla il suo stato di consegna fino a quando non si stabilizza su SERVING, NOT_SERVING o REJECTED. Usa campaigns:batchGetStatus per controllare fino a 100 campagne per chiamata.

curl --location 'https://apis.roblox.com/ads-management/v1/campaigns:batchGetStatus' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{ "campaignIds": ["1122334455"] }'

{
  "statuses": [
    { "id": "1122334455", "status": "ACTIVE", "deliveryStatus": "SERVING" }
  ]
}

Qualsiasi ID che non viene trovato o non è di proprietà del chiamante viene restituito in un array failures con motivo NOT_FOUND.

Gestisci una campagna

Usa PATCH /campaigns/{id} per mettere in pausa, riprendere, rinominare o modificare il budget. Invia solo i campi che stai cambiando.

curl --location --request PATCH 'https://apis.roblox.com/ads-management/v1/campaigns/1122334455' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{ "status": "PAUSED" }'

• Riprendi: invia { "status": "ACTIVE" }.
• Annulla: invia { "status": "CANCELLED" }. L'annullamento è permanente.
• Cambia budget: invia un nuovo budget.amountMicros. Un aumento si applica immediatamente; una diminuzione su una campagna in corso entra in vigore alla prossima mezzanotte nel fuso orario del conto di fatturazione, visualizzata come budget.scheduledAmountMicros e budget.scheduledEffectiveTime fino ad allora.

Report sulle prestazioni

Le metriche delle prestazioni della campagna—spesa, impressioni, riproduzioni e altro—vengono riportate tramite l'Analytics API, la casa per le metriche pubblicitarie e delle esperienze.

Errori comuni

Gli errori restituiscono un involucro con uno status HTTP, un breve title, un detail leggibile dall'uomo e un array errors in cui ogni voce ha un code stabile e leggibile dalla macchina e un message.

Pubblicità di articoli

Sponsorizza articoli del Marketplace come articoli per avatar, bundle e pass per aumentarne la visibilità su Roblox. Puoi creare e gestire sponsorizzazioni di articoli nel Gestore di articoli sponsorizzati o programmaticamente tramite gli endpoint delle campagne sponsorizzate su adconfiguration.roblox.com, elencati sotto Pubblicità nella documentazione API. Per ulteriori informazioni, vedi Articoli sponsorizzati.