المفاهيم الأساسية
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تقدّم هذه الصفحة نظرة عامة
على بنية واجهة برمجة تطبيقات "مدير إعلانات Google"، وتصف المفاهيم والمصطلحات العامة في "مدير الإعلانات".
بنية واجهة برمجة التطبيقات
في ما يلي رسم بياني مبسّط للفئات الرئيسية في واجهة برمجة تطبيقات "مدير الإعلانات" وكيفية ارتباطها ببعضها البعض:
طلب
- يحتوي عنصر
Order على معلومات عامة حول الطلب، مثل العملة أو مندوب المبيعات، ويحتوي على حالة LineItem واحدة أو أكثر. في الرموز البرمجية، يحمل كل LineItem رقم التعريف الذي يتضمّن Order بدلاً من Order الذي يتضمّن قائمة من عناصر LineItem.
LineItem
- يصف عنصر
LineItem مجموعة من المتطلبات لعرض الإعلان، بما في ذلك طريقة
ووقت عرض الإعلانات، وأحجام تصاميم الإعلانات
التي يجب عرضها وترتيب عرضها (بالترتيب أو الترجيح أو وفقًا لأدائها)،
وأولوية هذه الإعلانات، والعديد من الخصائص التي تصف بنية التكلفة. يحتوي LineItem على عنصر InventoryTargeting واحد يصف كائنات AdUnit وPlacement التي يمكنه استهدافها، بالإضافة إلى كائنات Targeting إضافية اختيارية من الفئة الفرعية تمثل معايير جغرافية أو مخصّصة أو أخرى.
LineItemCreativeAssociation
- تربط علامة
LineItemCreativeAssociation (غالبًا ما تُسمّى LICA) علامة LineItem واحدة بـ Creative. ويمكن ربط العناصر بأكثر من تصميم إعلان واحد، واستنادًا إلى نوع حسابك، قد تتمكّن من ربط تصميم إعلان بأكثر من عنصر واحد. عند إنشاء LineItemCreativeAssociation، يتحقّق "مدير الإعلانات" أولاً ممّا إذا كان تصميم الإعلان والعنصر متوافقَين.
وإذا اختلف الحجمان مثلاً، ستظهر لك رسالة خطأ عند محاولة إجراء الربط
أو تعديله. يتيح لك هذا الكائن أيضًا إلغاء بعض القيم في LineItem المرتبطة،
مثل تاريخَي البدء/الانتهاء، أو الحجم (إذا كان لديك تصميم إعلان لا
يناسب الحجم المحدّد في العنصر، ولكنّك مستعد للسماح لـ "مدير الإعلانات"
بتعديل حجم تصميم الإعلان ليلائم الوحدة الإعلانية بسرعة). لا تظهر إعلانات الأنشطة التجارية المحلية (LICA) في واجهة مستخدم "مدير إعلانات Google"، بل إنّها تمثّل اصطلاحًا في واجهة برمجة التطبيقات.
تصميم الإعلان
- تمثل
Creative الإعلان الفعلي. في حال استضافة الإعلان من خلال "مدير إعلانات Google"،
يحتفظ هذا العنصر بوحدات البايت الخاصة بالصور أو ملفات الفلاش أو علامات HTML المخصّصة المخزّنة
على خوادم "مدير الإعلانات"، وإذا تمت استضافة تصميم الإعلان على
موقع إلكتروني خارجي، يكون تصميم الإعلان عبارة عن عنوان URL أو مقتطف HTML الذي
ينفِّذ الطلب من الخادم التابع لجهة خارجية.
الفئات الفرعية لاستهداف المستودع الإعلاني
- يدرج العنصر
InventoryTargeting الوحدات الإعلانية المرتبطة بعنصر LineItem محدّد. يمكنك تحديد معايير استهداف إضافية واختيارية باستخدام مثيلات إضافية لفئة فرعية مناسبة من Targeting.
موضع إعلان
- كائن
Placement هو مجموعة من عنصر AdUnit واحد أو أكثر.
AdUnit
- يمثّل
AdUnit موقعًا جغرافيًا للإعلان على صفحة أو أكثر. يمكن أن يكون AdUnit استهدافًا لكائن InventoryTargeting الخاص بالسمة LineItem أو لكائن Placement. يتضمّن الكائن AdUnit حجمًا ومعرّفًا واسمًا فريدًا. يُستخدَم رقم التعريف لتحديد عناصر AdUnit الأخرى ضمن واجهة برمجة التطبيقات. ويُستخدم الاسم كمعرّف فريد في علامات HTML لتحديد عنصر AdUnit محدّد، ويتم إرساله مرة أخرى إلى "مدير إعلانات Google" كجزء من طلب الصفحة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Google Ad Manager API uses objects like Orders, Line Items, and Creatives to structure and manage ad campaigns.\u003c/p\u003e\n"],["\u003cp\u003eLine Items define ad requirements, targeting criteria, and cost structures, and are linked to Creatives via LineItemCreativeAssociations.\u003c/p\u003e\n"],["\u003cp\u003eCreatives represent the actual ads, which can be hosted by Ad Manager or a third-party server.\u003c/p\u003e\n"],["\u003cp\u003eAd Units represent ad locations on web pages and are targeted by Line Items or Placements, which are collections of Ad Units.\u003c/p\u003e\n"],["\u003cp\u003eInventory Targeting specifies which Ad Units are associated with a Line Item, while Targeting subclasses allow for additional criteria like geography or custom attributes.\u003c/p\u003e\n"]]],["The Google Ad Manager API's core components include `Order`, `LineItem`, `LineItemCreativeAssociation` (LICA), `Creative`, `InventoryTargeting`, `Placement`, and `AdUnit`. An `Order` contains `LineItem` instances, which define ad display requirements. A LICA links a `LineItem` to a `Creative`. `InventoryTargeting` links ad units to `LineItem`. `Placement` is a collection of `AdUnit`, representing ad locations. `Creative` is the actual ad content. AdUnits can be used to identify other adUnits.\n"],null,["# Basic Concepts\n\nThis page provides an overview\nof the architecture of the Google Ad Manager API and describes general concepts and terms in Ad Manager.\n\nAPI Architecture\n----------------\n\nHere is a simplified diagram of the main classes in the Ad Manager API, and how they relate to each other:\n\nOrder\n-----\n\n: An [Order](/ad-manager/api/reference/latest/OrderService.Order) object holds general information about the order such as the currency or salesperson, and contains one or more `LineItem` instances. In code, each `LineItem` holds the ID of its containing `Order`, rather than the `Order` holding a list of `LineItem` objects.\n\nLineItem\n--------\n\n: A [LineItem](/ad-manager/api/reference/latest/LineItemService.LineItem) object describes a set of requirements for an ad to show, including how\n and when the ads should be shown, the sizes of the creatives it should show and\n the order in which to show them (in order, weighted, or according to their performance),\n the priority of these ads, and many properties describing the cost structure. A\n `LineItem` has one `InventoryTargeting` object that describes which `AdUnit` and `Placement` objects it can target, and optional additional `Targeting` subclass objects that represent geographical, custom, or other criteria.\n\nLineItemCreativeAssociation\n---------------------------\n\n: A [LineItemCreativeAssociation](/ad-manager/api/reference/latest/LineItemCreativeAssociationService.LineItemCreativeAssociation) (often called a LICA) links one `LineItem` to\n one `Creative`. Line items can be linked to more than one creative, and depending on your account type, you might be able to link a creative to more than one line item. When you create a `LineItemCreativeAssociation`,\n Ad Manager first checks whether both the creative and the line item are compatible;\n if the sizes differ, for instance, you'll get an error when you try to create\n or update the association. This object also lets you override some values in the associated `LineItem`,\n such as start/end dates, or size (if you have a creative that doesn't\n quite fit the size specified by the line item, but you are willing to let Ad Manager\n adjust the size of the creative to fit the ad unit on the fly). LICAs are not exposed in the Ad Manager user interface; they are an API convention.\n\nCreative\n--------\n\n: A [Creative](/ad-manager/api/reference/latest/CreativeService.Creative) represents the actual ad. If the ad is hosted by Ad Manager,\n this object holds the actual image bytes, flash files, or custom HTML tags stored\n on Ad Manager's servers; if the creative is hosted on a\n third-party site, the creative is a URL or HTML snippet that makes the\n request from the third-party server.\n\nInventoryTargeting and Targeting subclasses\n-------------------------------------------\n\n: The [InventoryTargeting](/ad-manager/api/reference/latest/LineItemService.InventoryTargeting) object lists which ad units are associated with a specific `LineItem`. You can specify additional, optional targeting criteria using additional instances of an appropriate subclass of [`Targeting`](/ad-manager/api/reference/latest/LineItemService.Targeting).\n\nPlacement\n---------\n\n: A [Placement](/ad-manager/api/reference/latest/PlacementService.Placement) object is a collection of one or more `AdUnit` objects.\n\nAdUnit\n------\n\n: An [AdUnit](/ad-manager/api/reference/latest/InventoryService.AdUnit) represents an ad location on one or more pages. An `AdUnit` can be a target of either a `LineItem`'s `InventoryTargeting` object or a `Placement` object. An `AdUnit` object includes a size, an ID, and a unique name. The ID is used to identify other `AdUnit` objects within the API; the name is used as a unique identifier in the HTML tags to identify a specific `AdUnit` object, and is sent back to Ad Manager as part of the page request."]]
