API Marketing

Pubblico personalizzato dall'app mobile

Crea un pubblico basato sulle azioni delle persone nella tua app che soddisfano i tuoi criteri. Questa funzione ti consente di creare un pubblico che ha, ad esempio:

  • "Superato il livello 8 negli ultimi 10 giorni"
  • "Usato l'app negli ultimi 8 giorni ma non ha acquistato niente"
  • "Aggiunto al carrello ma non acquistato"

Questa soluzione usa eventi con nomi registrati tramite i nostri SDK di Facebook, l'API App Events o tramite Mobile Measurement Partners. Fra gli esempi di eventi da registrare vi sono: "Installato", "Aggiunto al carrello", "Acquistato" o "Raggiunto un livello".

Limitazioni

  • subtype per il pubblico personalizzato in base alle interazioni è supportato solo per il video.
  • Il pubblico personalizzato dall'app mobile per la targetizzazione di inclusione non è più supportato per l'endpoint POST /{ad-account-id}/adsets per le campagne SKAdNetwork di iOS 14.5.
  • Le nuove campagne per l'installazione di app iOS 14.5 non potranno più utilizzare la targetizzazione per connessioni di app.

Creazione di un pubblico

Per creare pubblico personalizzato dalla tua app mobile, l'account pubblicitario deve accettare le Condizioni d'uso per il pubblico personalizzato in Gestione inserzioni. Per accettare le condizioni d'uso:

  • Devi essere un utente Admin, Developer o Insights per l'account pubblicitario.
  • L'account pubblicitario deve essere elencato come account pubblicitario nelle impostazioni dell'app.

Per creare il tuo pubblico:

curl -X POST \
  -F 'name="My Test Website Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<APP_ID>",
                 "type": "app"
               }
             ],
             "retention_seconds": 8400,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "fb_mobile_purchase"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/customaudiences
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Test Website Custom Audience',
  'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
  'prefill' : '1',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Test Website Custom Audience',
  'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<appID>','type' => 'app')),'retention_seconds' => 8400,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'fb_mobile_purchase'))))))),
  'prefill' => '1',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Test Website Custom Audience',
  'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
  'prefill': '1',
}
print AdAccount(id).create_custom_audience(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCustomAudience()
      .setName(\"My Test Website Custom Audience\")
      .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<appID>\\",\\"type\\":\\"app\\"}],\\"retention_seconds\\":8400,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"fb_mobile_purchase\\"}]}}]}}\")
      .setPrefill(true)
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
customaudiences = ad_account.customaudiences.create({
    name: 'My Test Website Custom Audience',
    rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
    prefill: '1',
})

Restituisce l'id del pubblico creato con successo. Questi parametri sono i più rilevanti:

Nome Descrizione

name

tipo: Stringa

Obbligatorio.

Nome del tuo pubblico personalizzato.

description

tipo: Stringa

Facoltativo.

Descrizione del tuo pubblico personalizzato.

rule

tipo: oggetto JSON

Facoltativo.

Regola per definire il pubblico. Consulta Regole del pubblico.

Ogni account pubblicitario può creare un massimo di 200 segmenti di pubblico personalizzato tramite Pubblico personalizzato dalla tua app mobile. Effettua una richiesta POST a:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Usa questi campi:

Nome Descrizione

name

tipo: stringa

Obbligatorio.

Nome del tuo pubblico personalizzato.

retention_days

tipo: intero

Obbligatorio.

Per quanto tempo mantenere una persona in questo pubblico. Il minimo è 1. Il massimo è 180.


Se retention_days è 14 ed è il tredicesimo giorno e un membro del pubblico attiva un evento nell'app che corrisponde ai tuoi criteri, Facebook estende il tempo di mantenimento nel pubblico di altri 14 giorni. Una persona rimane nel pubblico per N giorni dall'ultimo evento corrispondente che ha attivato.

rule

tipo: Oggetto JSON

Obbligatorio.

Regole per definire il pubblico. Vedi Regole del pubblico.

Regole del pubblico

Per determinare chi viene aggiunto al pubblico personalizzato, definisci una regola in base agli eventi nella tua app. Una regola è un oggetto JSON con coppie chiave-valore che può fare riferimento a più eventi nell'app. Puoi definire la regola in base a eventi specifici e ai relativi parametri e anche all'aggregazione. Vedi Regole del pubblico per maggiori informazioni. Altri contenuti da consultare:

Esempi di regole del pubblico personalizzato dall'app mobile

Esempio di evento standard

Tutti gli acquirenti dell'app mobile negli ultimi 30 giorni per l'ID app 55064006:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
            }
        ]
    }
}

Esempio di evento personalizzato con parametri

Tutti gli utenti che hanno restituito eventi “timeOnPanel” personalizzati negli ultimi 30 giorni per l'ID app 55064006:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "timeOnPanel"
                        }
                    ]
                }
            }
        ]
    }
}

Tutti gli utenti che hanno restituito eventi “timeOnPanel” personalizzati in cui il valore dell'evento è maggiore di 30, il colore è “red” o “blue” e il dolce preferito contiene “banana”:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app",
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "timeOnPanel",
                        },
                        {
                            "field": "_value",
                            "operator": ">",
                            "value": 30,
                        },
                        {
                            "field": "color",
                            "operator": "is_any",
                            "value": ["red", "blue"],
                        },
                        {
                            "field": "favoriteDessert",
                            "operator": "contains",
                            "value": "banana",
                        }
                    ]
                }
            }
        ]
    }
}

Esempio di aggregazione

Il primo 20% di acquirenti in base agli acquisti negli ultimi 30 giorni:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
                "aggregation": {
                    "type": "count",
                    "method": "percentile",
                    "operator": "in_range",
                    "from": 75,  
                    "to": 100,
                }
            }
        ]
    }
}

Esempio di esclusioni

Il seguente esempio include le persone che hanno aggiunto al carrello, ma non hanno acquistato:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "add_to_cart"
                        }
                    ]
                }
            }
        ]
    },
    "exclusions": {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
            }
        ]
    }
}

API App Events

Interroga un'app su App Events e parametri riportati a Facebook. Puoi usare direttamente questi eventi e parametri per creare un pubblico personalizzato. Ti occorre un token d'accesso associato all'app_id con ruolo di amministratore, sviluppatore o inserzionista.

Effettua una richiesta GET:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_event_types

La risposta è JSON contenente un array data di dizionari JSON con questi campi:

Nome Descrizione

event_name

tipo: stringa

Tipo di evento nell'app da usare nella regola

display_name

tipo: stringa

Nome in forma leggibile del tipo di evento

description

tipo: stringa

Descrizione lunga dell'evento standard

parameters

tipo: array

Array di dizionari JSON che descrivono i parametri di questo evento {"parameter_name": "fb_currency","display_name": "Currency","description": "Currency for event"}


parameter_name: stringa, tipo di parametro dell'app da usare nella regola


display_name: stringa, nome in forma leggibile del tipo di evento


description: stringa, descrizione lunga del parametro, in caso di parametro standard


Gestione di un pubblico

Risorse