Esperienze interattive

Le Esperienze interattive sono una destinazione per inserzioni a schermo intero successiva al clic e caricata quasi istantaneamente dalle inserzioni nel feed.

Prima di iniziare

Per creare e gestire Esperienze interattive, hai bisogno di quanto segue:

• L'autorizzazione pages_manage_ads
• L'autorizzazione pages_read_engagement
• L'autorizzazione pages_show_list
• Poter eseguire l'attività ADVERTISE sulla Pagina

Limitazioni

• Tieni presente che puoi aggiornare solo Esperienze interattive non pubblicate.
• L'API Instant Experiences è disponibile per Instagram su base limitata.
• Le inserzioni che utilizzano Esperienze interattive non sono supportate per Facebook Stories.

Creazione

Per creare un'Esperienza interattiva, avrai bisogno dell'ID di una Pagina Facebook (PAGE-ID) e di qualsiasi elemento, quali foto, pulsanti e testo, che desideri includere nella tua esperienza.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_POST,
  $params)->getContent();

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/canvases

Elementi

Eliminazione di un elemento

Per eliminare un elemento, invia una richiesta DELETE con l'ID dell'elemento che desideri eliminare.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ELEMENT_ID>

Ottenere Esperienze interattive esistenti

Per ottenere informazioni su un'Esperienza interattiva esistente, avrai bisogno dell'ID dell'Esperienza interattiva (CANVAS-ID).

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();

curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Acquisizione di tutte le Esperienze interattive per una Pagina

Per ottenere informazioni su tutte le Esperienze interattive esistenti per una Pagina Facebook, avrai bisogno dell'ID della Pagina (PAGE-ID).

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'background_color',
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'last_editor',
    'name',
    'owner',
    'update_time',
  ),
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_GET,
  $params)->getContent();

curl -G \
  --data-urlencode 'fields=[ 
    "background_color", 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "last_editor", 
    "name", 
    "owner", 
    "update_time" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/canvases

Aggiornamento di un'Esperienza interattiva

Per aggiornare un'Esperienza interattiva, occorre annullare la pubblicazione dell'esperienza e saranno necessari l'ID dell'Esperienza interattiva (CANVAS-ID) e gli ID degli elementi che desideri aggiornare.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Uso di un modello

Puoi usare un modello per creare in modo rapido un'Esperienza interattiva per un obiettivo di business specifico. Il layout di ciascun modello è fisso, ma puoi sostituire i contenuti predefiniti con immagini, video, prodotti, testi e link.

Ottenere i tipi di elementi per un modello

Passaggio 1: ottenere le informazioni sul documento per il modello

Invia una richiesta GET per determinare quali elementi sono necessari per un particolare modello. Nell'esempio seguente, il modello è Acquisizione di nuovi clienti.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/133471657203838?fields=document&access_token=ACCESS-TOKEN"

Esempio di risposta

{
  "document": {
    "name": "Get New Customers",
    "id": "397246414010297"
  },
  "id": "133471657203838"
}

Passaggio 2: ottenere i tipi di elementi

Usa l'ID per il campo document per ottenere specifici elementi disponibili per un particolare modello.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/397246414010297?fields=body_elements&access_token=ACCESS-TOKEN"

La lista restituita mostra i tipi di elementi disponibili per l'uso nel modello Acquisizione di nuovi clienti.

    {
  "body_elements": [
    {
      "name": "Cover Image or Video",
      "element_type": "PHOTO",
      "id": "397271930674412"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271920674413"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271910674414"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271914007747"
    },
    {
      "name": "Carousel",
      "element_type": "CAROUSEL",
      "id": "397271940674411"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271917341080"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271924007746"
    }
  ],
  "id": "397246414010297"
}

Pubblicazione

Per pubblicare la tua inserzione con Esperienza interattiva invia una richiesta POST all'ID della tua Esperienza interattiva (CANVAS-ID) e imposta il campo is_published su true.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'is_published' => true,
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();

curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CANVAS_ID>

Creazione di una creatività dell'inserzione

Crea una creatività dell'inserzione usando il link per un'Esperienza interattiva esistente (CANVAS-LINK).

curl -X POST \
  -F 'image_hash="<IMAGE_HASH>"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "<CANVAS_LINK>",
         "name": "Creative message",
         "call_to_action": {
           "type": "LEARN_MORE"
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adcreatives

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const AdCreative = bizSdk.AdCreative;

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 = {
  'image_hash' : '<imageHash>',
  'object_story_spec' : {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}},
};
const adcreatives = (new AdAccount(id)).createAdCreative(
  fields,
  params
);
logApiCallResult('adcreatives api call complete.', adcreatives);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
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(
  'image_hash' => '<imageHash>',
  'object_story_spec' => array('page_id' => '<pageID>','link_data' => array('image_hash' => '<imageHash>','link' => '<canvasURI>','name' => 'Creative message','call_to_action' => array('type' => 'LEARN_MORE'))),
);
echo json_encode((new AdAccount($id))->createAdCreative(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.adcreative import AdCreative
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 = {
  'image_hash': '<imageHash>',
  'object_story_spec': {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}},
}
print AdAccount(id).create_ad_creative(
  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).createAdCreative()
      .setImageHash(\"<imageHash>\")
      .setObjectStorySpec(
          new AdCreativeObjectStorySpec()
            .setFieldLinkData(
              new AdCreativeLinkData()
                .setFieldCallToAction(
                  new AdCreativeLinkDataCallToAction()
                    .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_LEARN_MORE)
                )
                .setFieldImageHash(\"<imageHash>\")
                .setFieldLink(\"<canvasURI>\")
                .setFieldName(\"Creative message\")
            )
            .setFieldPageId(\"<pageID>\")
        )
      .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)
adcreatives = ad_account.adcreatives.create({
    image_hash: '<imageHash>',
    object_story_spec: {'page_id':'<pageID>','link_data':{'image_hash':'<imageHash>','link':'<canvasURI>','name':'Creative message','call_to_action':{'type':'LEARN_MORE'}}},
})

Quando la creatività dell'inserzione è pronta, puoi procedere alla creazione di gruppo di inserzioni e campagna pubblicitaria.

Finestra di dialogo Inserzioni Esperienze interattive

Puoi usare la finestra di dialogo Inserzioni Esperienze interattive per dotare il tuo sito web delle interfacce utente di Facebook per la creazione di inserzioni Esperienze interattive. Per maggiori dettagli sul componente dell'interfaccia utente, consulta Finestre di dialogo.

Per configurare l'SDK di Facebook per JavaScript, consulta:

• Guida di avvio rapido
• Riferimento per l'inizializzazione

L'SDK JavaScript si basa sulle autorizzazioni dell'utente connesso per creare un'Esperienza interattiva. Se l'utente non dispone delle autorizzazioni necessarie per creare un'Esperienza interattiva per la pagina e l'azienda forniti, la finestra di dialogo mostra un errore. Per garantire l'assenza di errori, l'utente deve far parte dell'azienda e possedere le autorizzazioni per la creazione di inserzioni per la Pagina.

Quindi, attiva la finestra di dialogo:

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_builder',
  business_id: '<BUSINESS_ID>',
  page_id: '<PAGE_ID>'
}, function(response) {
  // callback
});

Puoi usare queste impostazioni per il plug-in:

Il parametro canvas_id è facoltativo e il suo scopo è consentire a un utente di modificare o visualizzare in anteprima un'Esperienza interattiva esistente. Se un'Esperienza interattiva è completa, non puoi modificarla. Per visualizzare un'anteprima di un'Esperienza interattiva, è consigliabile utilizzare la finestra di dialogo Anteprima Esperienze interattive.

Se l'operazione viene eseguita correttamente, il plug-in fornirà questa risposta:

{
  "success": true,
  "id": "CANVAS-ID"
}

L'ID restituito è un'Esperienza interattiva pubblicata. Ora puoi usarlo nelle campagne pubblicitarie. Se non viene restituita alcuna risposta o viene restituita una risposta undefined, l'utente ha chiuso la finestra di dialogo prima di terminare l'Esperienza interattiva. Potrebbe aver salvato le Esperienze interattive, ma non averle terminate. Puoi estrarre tutte le Esperienze interattive che appartengono a una pagina utilizzando l'API Graph per vedere se ci sono esperienze non terminate.

Anteprima di un'Esperienza interattiva

API Iframe Preview

Puoi generare un'anteprima di un'esperienza interattiva chiamando l'API previews che restituisce un iframe, simile all'API ad previews:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v18.0/<CANVAS_ID>/preview

L'API restituisce un risultato simile a questo, che può essere visualizzato incorporando l'elemento iframe restituito in HTML:

{
"data": [
    {
      "body": "<iframe src=\"https://www.facebook.com/ads/canvas/preview?d=AQKELApdJxoVp2f3PHl8-pRtYuAh4-_eDupMDbh-pS9zde_EFxckhYQCXu7NYUi4PhhBA7uskIo2Ys3IjIVNGZiS&t=AQKGOPqGI-NWcv1YKbA\" width=\"405\" height=\"720\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
    }
  ],
  "__www_request_id__": "AQnyr47Qp2r5M-ISqSiMgrw"
}

SDK di Facebook

Puoi usare questa finestra di dialogo per visualizzare un'anteprima di un'Esperienza interattiva nel modo in cui un utente su Facebook la vedrebbe dal tuo sito web. Per maggiori dettagli sul componente dell'interfaccia utente, consulta le Finestre di dialogo.

Per configurare l'SDK di Facebook per JavaScript, consulta:

• Guida di avvio rapido
• Riferimento per l'inizializzazione

L'SDK JavaScript si basa sulle autorizzazioni dell'utente che ha effettuato l'accesso per creare un'Esperienza interattiva. Se l'utente non dispone delle autorizzazioni necessarie per visualizzare l'Esperienza interattiva, la finestra di dialogo mostra un errore.

Quindi, attiva la finestra di dialogo di anteprima:

FB.ui({         
  display: 'popup',
  method: 'instant_experiences_preview',
  canvas_id: 'CANVAS-ID'
});

Puoi usare queste impostazioni per il plug-in:

Creazione di gruppi di pubblico per le Esperienze interattive

Per creare un pubblico in base alle interazioni, ovvero un pubblico di persone che hanno interagito con un'Esperienza interattiva, imposta il parametro object_id del campo rule sull'ID dell'Esperienza interattiva (CANVAS-ID) nella tua chiamata POST /act_AD-ACCOUNT/customaudiences.

Persone che hanno aperto l'Esperienza interattiva

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who opened this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_document_open"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Persone che hanno cliccato su un qualsiasi link nell'Esperienza interattiva

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who clicked any links in this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_element_click"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \  
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Per maggiori informazioni sul pubblico personalizzato, consulta il riferimento per il pubblico personalizzato.

Esperienze interattive e inserzioni su Instagram

Per l'implementazione delle Esperienze interattive su Instagram, occorre usare la stessa chiamata API impiegata per l'Esperienza interattiva su Facebook. Esistono delle limitazioni quando usi Instagram e le Esperienze interattive:

• Posizionamenti: disponibili per il feed di Instagram e Instagram Stories. Se selezioni Instagram Stories, devi selezionarlo come posizionamento pubblicitario esclusivo.
• Elementi Esperienza interattiva: sono supportati interamente intestazioni e insiemi di prodotti.

Sono supportati parzialmente i seguenti elementi di Esperienza interattiva su Instagram:

• Piè di pagina: nessun supporto per swipe to open; nei client viene reso con Tap to open.
• Carosello: nessun supporto di foto collegate a un'altra Esperienza interattiva; nel client il link viene visualizzato come non cliccabile. Per le foto e i video, nessun supporto per Adatta all'altezza, Adatta alla larghezza o Inclina per la visualizzazione panoramica; vengono resi come Adatta alla larghezza.
• Pulsante: impossibile inserire un link a un'altra Esperienza interattiva o all'App Store.
• Testo: nessun supporto per linguaggio formattato da destra a sinistra.
• Video: nessun supporto per video a 360°.
• Strumenti di localizzazione dei punti vendita: non supportati.

Insight sulle inserzioni

Consulta Insights sulle inserzioni per una panoramica e la descrizione delle metriche disponibili.

Altri contenuti da consultare

• Guida alle inserzioni di Facebook: Specifiche delle Esperienze interattive
• Visita il Centro assistenza: Scopri di più sulle Esperienze interattive