إدارة حالة كائن الإعلان

تتضمن الحملة الإعلانية والمجموعة الإعلانية والإعلانات أحد أنواع الحالات التالية:

منشور
مؤرشف
محذوف

للحصول على المعلومات الأساسية، يمكنك الرجوع إلى مدونة مطوّري الإعلانات، الإعلانات المحذوفة مقابل المؤرشفة.

منشور

يمكن أن تتضمن كائنات الإعلانات المنشورة الحالات التالية:

ACTIVE
PAUSED
PENDING_REVIEW
CREDIT_CARD_NEEDED
PREAPPROVED
DISABLED
PENDING_PROCESS
WITH_ISSUES

مؤرشف

يمكنك تعيين كائن الإعلان إلى ARCHIVED من خلال تعيين الحقل status إلى ARCHIVED. وعند تعيين حالة أحد الكائنات إلى ARCHIVED، يمكنك متابعة الاستعلام عن التفاصيل والإحصاءات استنادًا إلى معرف الكائن. وعلى الرغم من ذلك، يوجد حد أقصى لعدد الكائنات التي يمكنك أرشفتها. وبالتالي يجب أن تلتزم بهذا التقييد وتقوم بتغيير الحالة إلى DELETED عندما لم تعد تحتاج إلى أي كائن.

لا يتوفر للكائن ARCHIVED سوى حقلين يمكنك تغييرهما وهما: name وstatus. ولا يمكنك أيضًا سوى تغيير status إلى DELETED.

محذوف

قم بتعيين كائن الإعلان إلى DELETED من خلال تعيين الحقل status إلى DELETED أو إرسال HTTP DELETE إلى هذا الكائن. وبمجرد تعيين حالة كائن ما إلى DELETED، فلا يمكن إعادة تعيينها مرة أخرى إلى ARCHIVED.

إذا احتفظت بمعرف الكائن المحذوف، يمكنك متابعة استعادة الإحصاءات أو تفاصيل الكائن من خلال الاستعلام عن معرف الكائن. وعلى الرغم من ذلك، لا يمكنك استعادة الكائنات المحذوفة ككائن اتصال من عقدة أو كائن غير محذوف. فعلى سبيل المثال، تعمل <API_VERSION>/<AD_ID>/insights لكائن محذوف إلا أن <API_VERSION>/act_<AD_ACCOUNT_ID>/insights?level=ad لا تقم بإرجاع إحصاءات الكائن المحذوف.

بعد أن تحذف إعلانًا، فقد يظل يتتبع عدد مرات الظهور والنقرات والإجراءات لمدة 28 يومًا بعد آخر تاريخ عرض له. ويمكنك الاستعلام عن رؤى كائنات DELETED باستخدام الفلتر ad.effective_status.

إذا كانت لديك مجموعة إعلانية تحتوي على إعلانين بداخلها وقمت بحذف إعلان واحد منهما، فلن يعمل الاستعلامان التاليان على إرجاع النتائج نفسها:

https://graph.facebook.com/v21.0/<AD_SET_ID>/insights
https://graph.facebook.com/v21.0/<AD_ID>/insights

تقوم المجموعة الإعلانية بإرجاع إحصاءات عن الإعلانات المحذوفة وغير المحذوفة بداخلها. وعلى الرغم من أنه في حالة الاستعلام عن الإعلانات الموجودة في المجموعة الإعلانية، سيظهر لك إعلان واحد فقط:

https://graph.facebook.com/v21.0/<AD_SET_ID>/ads

لتجنب حدوث هذا السيناريو، يجب حذف الإعلانات بعد مرور 28 يومًا على آخر تاريخ لعرضها من أجل ضمان عدم إجراء أي تغيير على الإحصاءات بعد ذلك. ويجب تخزين الإحصاءات أو المعرفات الخاصة بهذه الكائنات في نظامك الخاص قبل حذفها. علمًا بأن هذه التوصية اختيارية:

إذا لم يعرض تطبيقك تقسيم الإحصاءات، أو
لا تهتم بما إذا كان مجموع تقسيمات الإحصاءات غير مطابق لإحصاءات الكائن الأصلي بسبب حذف بعض الكائنات الفرعية.

لا يمكنك تغيير أي حقل باستثناء name للكائن DELETED.

إدارة الحالة

فيما يلي الطريقة المُستخدمة عادة لإدارة حالة الكائن:

يمكنك إنشاء كائنات الإعلانات، ثم تشغيلها وبدء عرضها
عندما تحذف أحد الكائنات، فإننا نحذفه تلقائيًا
عندما تصل إلى حد الكائنات المؤرشفة المسموح به، لا يمكنك بعد ذلك أرشفة المزيد من الكائنات.
يجب نقل الكائنات المحذوفة المؤرشفة إلى الحالة deleted لتقليل التقييدات المفروضة.

تعمل الحالة الخاصة بكائنات الإعلان بالطريقة التالية فيما يتعلق بالتدرج الخاص بكائنات الإعلان:

إذا تم تعيين حالة الحملة الإعلانية على with_issues أو paused أو archived أو deleted في حملة إعلانية، فسترث كل الكائنات التي تندرج ضمن هذه الحملة هذه الحالة تلقائيًا.
إذا تم تعيين الحملة الإعلانية على deleted، فلا يمكنك استرداد المجموعات الإعلانية أو الإعلانات التي تندرج ضمن هذه الحملة الإعلانية من دون تحديد المعرفات بشكل صريح.
إذا تم تعيين حالة الإعلان على with_issues أو paused أو archived أو deleted، فستظل الحملة الإعلانية أو المجموعة الإعلانية التي تحتوي على هذا الإعلان محتفظة بحالتها الأصلية وستكون متاحة للاسترداد.

تنطبق التقييدات التالية على كائنات بالحالة ARCHIVED في حساب إعلاني محدد:

100,000 للحملات الإعلانية
100,000 للمجموعات الإعلانية
100,000 للإعلانات

في حالة الاطلاع على عناصر الربط بالحالة archived، يجب أن تضع فلترًا خاصًا للكائنات المؤرشفة لأننا لا نقوم بإرجاعها بشكل افتراضي. وفي حالة الاطلاع على إحصاءات أحد كائنات الإعلانات، نقوم بتضمين الإحصاءات الخاصة بجميع الكائنات الفرعية بغض النظر عما إذا كان الكائن الفرعي يتوفر بالحالة active أم archived أم deleted. وبالتالي لا تحتاج إلى فلترة الرؤى المتعلقة بالكائنات الفرعية.

مقارنات بين الحالات المختلفة

تختلف الكائنات بحالات مثل ACTIVE أو PAUSED عن الكائنات بالحالتين ARCHIVED وDELETED. وتتضح فيما يلي الاختلافات الرئيسية.

استعلام	منشور	مؤرشف	محذوف
موجودة في قاعدة البيانات	نعم	نعم	نعم
أقصى عدد لكل حساب إعلاني	مع تقييدات	100,000	بلا تقييدات
الاستعلام كعناصر ربط دون فلترة	نعم	لا	لا
استعلام كعناصر ربط مع فلترة الحالة	نعم بالنسبة للكائنات بالحالة المُضمنة في الفلتر	نعم إذا كان فلتر الحالة يتضمن `ARCHIVED`.	لا إذا كان فلتر الحالة لا يتضمن `DELETED`، ويظهر خطأ إذا كان يحتوي على ذلك.
الاستعلام حسب المعرف الخاص	نعم	نعم	نعم
الإحصاءات المُجمعة في `/<PARENT_OBJECT_ID>/insights`	نعم	نعم	نعم
الإحصاءات المُدرجة في قائمة نتائج `/<PARENT_OBJECT_ID>/insights?level=<OBJECT_LEVEL>`	نعم	لا	لا
الإحصاءات المُدرجة في قائمة نتائج `/<PARENT_OBJECT_ID>/insights` مع فلترة delivery_info	نعم بالنسبة للكائنات بالحالة المُضمنة في الفلتر	نعم بالنسبة للكائنات بالحالة المُضمنة في الفلتر	لا
الرؤى المعروضة مع `/<OBJECT_ID>/insights`	نعم	نعم	نعم
يمكن تغيير الحالة إلى	أي حالة صالحة	`DELETED`	لا يمكن التغيير

لتعيين إعلان مطلوب أرشفته:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->archive();

from facebookads.adobjects.ad import Ad

ad = Ad(ad_id)
ad.remote_archive()

new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_ARCHIVED)
  .execute();

curl \
  -F 'status=ARCHIVED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>

لحذف إعلان:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->deleteSelf();

from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_delete()

new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_DELETED)
  .execute();

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

لاستعادة كائنات فرعية منشورة من كائن منشور، فعلى سبيل المثال، كل الإعلانات المنشورة ضمن حملة إعلانية ولا تتضمن إعلانات بالحالة ARCHIVED أو DELETED:


curl -X GET \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_CAMPAIGN_ID>/ads

Open In Graph API Explorer


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

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_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 = [
  'name',
];
params = {
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);

Open In Graph API Explorer


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

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
  'name',
);
$params = array(
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);

Open In Graph API Explorer

View on GitHub


from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

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

fields = [
  'name',
]
params = {
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)

Open In Graph API Explorer

View on GitHub


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_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .requestNameField()
      .execute();

  }
}

Open In Graph API Explorer

View on GitHub


require 'facebook_ads'

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

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

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
})

Open In Graph API Explorer

View on GitHub

لاستعادة كائنات فرعية بالحالة ARCHIVED لكائن منشور، فعلى سبيل المثال كل الإعلانات بالحالة ARCHIVED لإحدى المجموعات الإعلانية، يلزم استخدام فلتر الحالة:


curl -X GET \
  -d 'effective_status=[
       "ARCHIVED"
     ]' \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<AD_CAMPAIGN_ID>/ads

Open In Graph API Explorer


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

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_CAMPAIGN_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 = [
  'name',
];
params = {
  'effective_status' : ['ARCHIVED'],
};
const adss = (new Campaign(id)).getAds(
  fields,
  params
);
logApiCallResult('adss api call complete.', adss);

Open In Graph API Explorer


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

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
  'name',
);
$params = array(
  'effective_status' => array('ARCHIVED'),
);
echo json_encode((new Campaign($id))->getAds(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);

Open In Graph API Explorer

View on GitHub


from facebook_business.adobjects.campaign import Campaign
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

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

fields = [
  'name',
]
params = {
  'effective_status': ['ARCHIVED'],
}
print Campaign(id).get_ads(
  fields=fields,
  params=params,
)

Open In Graph API Explorer

View on GitHub


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_CAMPAIGN_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Campaign(id, context).getAds()
      .setEffectiveStatus(\"[\\"ARCHIVED\\"]\")
      .requestNameField()
      .execute();

  }
}

Open In Graph API Explorer

View on GitHub


require 'facebook_ads'

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

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

campaign = FacebookAds::Campaign.get(id)
adss = campaign.ads({
    fields: { 'name' },
    effective_status: ['ARCHIVED'],
})

Open In Graph API Explorer

View on GitHub