Topics API برای موبایل: نمای کلی

درباره API مربوط به موضوعات (Topics API) در اندروید و مراحل پیاده‌سازی آن اطلاعات کسب کنید. همچنین می‌توانید مستقیماً به پیاده‌سازی موضوعات (topics) بپردازید.

How the Topics API works

The Topics API can be used to observe and provide access to topics that appear to be of interest to the user, based on their activity. The Topics API can then give API callers (such as ad tech platforms) access to a user's topics of interest, but without revealing additional information about the user's activity.

Key concepts

• A topic is a human-readable topic of interest for the current user and is part of the Topics taxonomy.
• A caller is an entity, such as an app, a third-party SDK, a website, or service, that makes a request to the Topics API to observe or access a user's interests.
• A topic is observed by a caller, if the caller made a Topics API request from a web page or app associated with this topic during the past three epochs.
• An epoch is a period of topic computation, which defaults to one week.
• A taxonomy is a hierarchical list of categories, which includes, for example, such categories as /Arts & Entertainment/Music & Audio/Soul & R&B and /Business & Industrial/Business Services/Corporate Events.
• Topics are derived using a classifier model that maps user activity to zero or more topics.

Topics API flow core steps

The Topics API lifecycle has three main steps:

• Observe user activity, such as when they visit the web page https://cats.example/tabby/index.html or download the app cats.
• Derive topics from user activity, for example /Pets & Animals/Pets/Cats.
• Access topics previously observed for the user, for example as a signal to select relevant advertising (such as a cat food promotion).

Observe topics

Callers can only access topics of interest that they've observed. A caller observes a topic when they make a Topics API request from a context associated with this topic. To illustrate this concept, consider the following simplified example.

• Suppose there are two Topics API callers: A and B.
• There are two contexts:
  • Greenhouse, for example an app named Greenhouse or a website greenhouse.example, associated with the topic Home & Garden.
  • Tennis exercises, for example an app named Tennis Exercises or a website tennis.example, associated with the topic Sports/Tennis.
• Both caller A and B are present in the context of Greenhouse.
• Only the caller B is present in the context of Tennis exercises.
• Assume that no topics were observed for the user before epoch 1, for the sake of simplification.
• The user visits the Greenhouse app, and callers A and B make a Topics API call to record the user visit to the page or app (see the implementation guide suggested in Next steps to find out how to call the Topics API). This record (a hostname or app data) is later used to derive topics of interest. The Topics API will later mark the topic Home & Garden as observed by both callers A and B.
• The user visits the Tennis exercises app. Only the caller B sends a Topics API request. The Topics API will later mark the topic Sports/Tennis as observed by the caller B.
• By the end of the epoch, the Topics API refreshes the user's top topics and determines the callers that observed these topics based on user activity.
• Later, when the caller B makes another Topics API call, it can get either Home & Garden or Sports/Tennis topic (or, with a 5% chance, a random topic) for this user in the response array.
• Caller A can only access the topic Home & Garden, as it has never observed the topic Sports/Tennis. This means that a third-party will only learn about a user's topic of interest within the specific context (app or website) where it is present.

Derive topics

Topics derives topics of interest from user activity. The topics are selected from a predefined open-source taxonomy. Once per epoch, Topics refreshes the user's top five topics and the callers that observed them during the epoch. The Topics classifier model derives topics from user activity: hostname for a web page visit, app information on Android.

Caller accesses user's topics of interest

The API returns only topics that have been observed by the caller within the most recent three epochs. A maximum of three topics may be returned to a caller,one topic for each of the three recent epochs (if the caller observed topics for that epoch). The returned topics can be used by the caller to supplement any contextual information and can be combined to help find a more relevant ad for the user.

Epochs

The Topics API must ensure that the topics of interest it provides are kept up to date. The topics are inferred for a user based on their activity during a period of time known as an epoch, one week by default. Each user has their own epochs (epochs are "per user") and the initial start time is randomized.

Once each epoch, the Topics API computes the user's top five topics and determines which callers observed those topics using on-device information. The topic selected for each epoch is randomly selected from the user's top five topics for that time period. To further enhance privacy and ensure that all topics may be represented, there is a 5% chance the topic is randomly selected from all possible topics in the taxonomy of interests.

مباحث مربوط به اندروید در عمل

API موضوعات در اندروید برای پشتیبانی از SDKهای تبلیغاتی شخص ثالث طراحی شده است که معمولاً در چندین برنامه کار می‌کنند. موضوعات موضوعات تبلیغاتی جزئی و مورد علاقه تماس‌گیرندگان را بر اساس استفاده کاربر از برنامه، بدون تکیه بر شناسه‌های بین برنامه‌ای، در اختیار تماس‌گیرندگان قرار می‌دهد. این موضوعات می‌توانند برای تکمیل هرگونه اطلاعات زمینه‌ای مربوط به برنامه‌ای که می‌خواهد تبلیغی را نمایش دهد، استفاده شوند و می‌توانند برای کمک به انتخاب یک تبلیغ مناسب برای کاربر ترکیب شوند.

در زمینه API موضوعات، خریداران و تبلیغ‌کنندگان به سمت فروش وابسته هستند. این سمت فروشنده است که حضور گسترده‌ای در برنامه‌های ناشر دارد و موضوعات کاربران را مشاهده می‌کند و سپس موضوعات را با خریداران به اشتراک می‌گذارد تا به آنها در انتخاب تبلیغات مرتبط‌تر کمک کند. برای دریافت موضوعات، برنامه‌ها و SDK های سمت فروش باید با مشاهده API موضوعات برای حداقل یک دوره، ردپایی از خود ایجاد کنند.

برای مشاهده‌ی نمونه‌های کدی که نحوه‌ی تنظیم قابلیت دریافت موضوعات برای تبلیغات مبتنی بر علایق را نشان می‌دهند، به راهنمای پیاده‌سازی API موضوعات مراجعه کنید.

ادغام موضوعات بر اساس نوع کسب و کار

تبلیغات مبتنی بر علاقه (IBA) را با API تاپیکز فعال کنید. مراحل را بر اساس نوع کسب و کار فناوری تبلیغات خود دنبال کنید تا API تاپیکز را ادغام کنید و برای راه‌اندازی آماده شوید.

برای همه تکنسین‌های تبلیغات

• طبقه‌بندی موضوعات را مرور کنید و بازخورد ارائه دهید.
• با برنامه‌های نمونه API موضوعات آزمایش کنید تا ببینید کدام داده‌های موضوعات از طبقه‌بندی‌کننده روی دستگاه بازگردانده می‌شوند.
• جریان‌های برنامه و SDK را به‌روزرسانی کنید تا فراخوانی API مربوط به موضوعات (Topics API) آغاز شود.
• پروتکل‌ها را به‌روزرسانی کنید تا ارسال موضوعات در درخواست‌های تبلیغاتی آغاز شود.
• فناوری تبلیغات خود را در Privacy Sandbox ثبت کنید .

برای تکنسین‌های تبلیغات سمت فروش

• برای ایجاد ردپای API تاپیک‌ها، به عنوان ناظر عمل کنید. API تاپیک‌ها سیگنال جدیدی ارائه می‌دهد، بنابراین برای شروع فراخوانی API تاپیک‌ها، باید SDK خود را به‌روزرسانی کنید. برای بازیابی مداوم تاپیک‌ها، SDK شما باید حداقل یک بار در هر دوره، API را از برنامه‌های ناشر فراخوانی کند. برای دریافت حداکثر تعداد تاپیک‌ها (سه تاپیک) برای ارسال با درخواست‌های تبلیغاتی شما، تا چهار دوره طول می‌کشد.
• اطلاعات API تاپیکز را در درخواست‌های تبلیغاتی خود لحاظ کنید. برای هر درخواست تبلیغاتی، داده‌های API تاپیکز خود را با شرکای طرف خرید به اشتراک بگذارید. API تاپیکز قصد دارد سیگنال‌های دیگر (مانند سیگنال‌های زمینه‌ای) را تکمیل کند تا به یافتن تبلیغ مناسب برای یک بازدیدکننده خاص کمک کند.
• روی پروتکلی برای اشتراک‌گذاری موضوعات با شرکای طرف خرید خود همکاری کنید. API موضوعات به هر SDK نیاز دارد تا با شرکای پایین‌دستی همکاری کند تا در مورد نحوه اشتراک‌گذاری داده‌های API موضوعات به توافق برسند.

برای تکنسین‌های تبلیغات سمت خریدار

• با شرکای سمت فروش ارتباط برقرار کنید تا برنامه‌های آنها برای مشاهده موضوعات و ایجاد ردپا را تأیید کنید. برای دریافت موضوعات، ارائه دهندگان سمت فروش باید حداقل یک بار در هر دوره، API موضوعات را فراخوانی کنند.
• روی پروتکلی برای دریافت موضوعات از شرکای سمت فروش خود همکاری کنید. موضوعات، سیگنال جدیدی است که به عنوان بخشی از درخواست تبلیغ توسط شرکای سمت فروش به اشتراک گذاشته می‌شود. مصرف‌کنندگان سمت خرید باید مطمئن شوند که با شرکای بالادستی خود در مورد نحوه اشتراک‌گذاری موضوعات همکاری می‌کنند.
• موضوعات را در مدل‌های پیشنهاد قیمت و بهینه‌سازی بگنجانید. انتظار می‌رود API موضوعات، سیگنال‌های دیگری مانند زمینه را تکمیل کند تا به یافتن تبلیغ مناسب برای بازدیدکننده کمک کند.

چگونه API موضوعات یک برنامه را استنباط می‌کند

در اندروید، API مربوط به موضوعات، موضوعات یک برنامه را بر اساس اطلاعات برنامه و با استفاده از یک مدل طبقه‌بندی کننده استنباط می‌کند. در پیاده‌سازی فعلی، موضوعات از نام برنامه و بسته برای اختصاص موضوعات مورد علاقه به یک برنامه استفاده می‌کنند، اما این ممکن است بعداً گسترش یابد تا اطلاعات دیگری مانند توضیحات برنامه را نیز شامل شود.

طبقه‌بندی‌کننده موضوع

موضوعات مورد علاقه از یک مدل طبقه‌بندی کننده که بر اساس اطلاعات برنامه در دسترس عموم آموزش دیده است، استخراج می‌شوند.

• وقتی از مدل طبقه‌بندی برای استنتاج محاسبه موضوعات برای یک دوره معین استفاده می‌شود، مجموعه سیگنال‌های مورد استفاده روی دستگاه باقی می‌مانند. این مجموعه سیگنال‌ها ممکن است شامل برنامه‌های نصب شده یا اخیراً استفاده شده باشد و بعداً ممکن است برای شامل شدن سیگنال‌های دیگر گسترش یابد.
• مدل V5 توسط گوگل بر روی ۵۴۰،۰۰۰ اطلاعات برنامه برچسب‌گذاری شده توسط انسان و ۱۷ میلیون اطلاعات برنامه برچسب‌گذاری شده توسط ماشین که به صورت عمومی از فروشگاه‌های برنامه مانند فروشگاه Google Play در دسترس هستند، آموزش داده شده است. این مدل از نام برنامه‌ها و نام بسته‌ها به عنوان سیگنال‌های ورودی استفاده می‌کند و به صورت رایگان در دسترس توسعه‌دهندگان برنامه قرار دارد تا آن را آزمایش کنند و ببینند برنامه آنها در چه موضوعاتی طبقه‌بندی می‌شود.
• ممکن است یک برنامه به بیش از یک موضوع نگاشت شود، یا به هیچ موضوعی نگاشت نشود، یا اینکه به تاریخچه موضوعات کاربر اضافه نشود. در صورتی که یک برنامه به بیش از یک موضوع در طبقه‌بندی نگاشت شود، تعداد موضوعات انتخاب شده برای این برنامه به سه مورد برتر محدود خواهد شد.

برای درک بهتر نحوه‌ی عملکرد مدل طبقه‌بندی، می‌توانید با استفاده از Android Topics Classifier Colab، تأثیر داده‌های مختلف برنامه بر طبقه‌بندی را آزمایش کنید.

طبقه‌بندی

موضوعات از یک طبقه‌بندی متن‌باز از پیش تعریف‌شده انتخاب می‌شوند. این طبقه‌بندی به صورت عمومی در دسترس است و ممکن است تغییر کند. پیشنهادات را می‌توان با استفاده از دکمه بازخورد در بالای این صفحه ثبت کرد. این طبقه‌بندی توسط انسان تنظیم شده است، بنابراین موضوعات حساس بخشی از طبقه‌بندی نیستند. این طبقه‌بندی متناسب با دسته‌های تبلیغاتی که می‌توانند در برنامه‌های تلفن همراه در اندروید نمایش داده شوند، تنظیم خواهد شد.

مباحث مربوط به اندروید در عمل

فرض کنید کاربری هفت برنامه روی دستگاهش نصب کرده است: A، B، C، D، E، F و G. فرض کنید طبقه‌بندی موضوعی برنامه و SDKهای فناوری تبلیغات در این برنامه‌ها به شرح زیر است:

پایان هفته اول: API موضوعات، 5 موضوع برتر کاربر را برای این دوره تولید می‌کند.

در هفته دوم، اگر یک فراخوانی‌کننده در هر برنامه‌ای، API را فراخوانی کند، لیست موضوعات بازگشتی فقط شامل موضوعاتی خواهد بود که فراخوانی‌کننده در ستون «تماس‌گیرندگانی که می‌توانند درباره موضوع اطلاعات کسب کنند» برای آن موضوع، برای آن برنامه و برای آن دوره زمانی قرار دارد.

• پنجره تاریخچه که در محاسبه موضوعات موجود برای هر تماس گیرنده لحاظ شده است، سه دوره (یا سه هفته) است.
• فقط تاپیک‌های مرتبط با برنامه‌هایی که API تاپیک‌ها را از طریق SDKهای تبلیغاتی فراخوانی می‌کنند، استفاده می‌شوند. این بدان معناست که اگر یک برنامه شامل هیچ SDK تبلیغاتی که API تاپیک‌ها را فراخوانی می‌کند، نباشد، تاپیک‌های مرتبط با آن برنامه به مجموعه تاپیک‌های قابل دسترسی توسط SDKهای تبلیغاتی اضافه نمی‌شوند.
• یک برنامه همچنین می‌تواند به صورت اعلانی از API موضوعات (Topics API) انصراف دهد . موضوعات مرتبط با برنامه‌های انصراف داده شده در محاسبه هفتگی موضوعات مشارکت نخواهند داشت. این سند به‌روزرسانی خواهد شد تا جزئیات پیاده‌سازی مرتبط را شامل شود.

اگر تعداد استفاده از برنامه به اندازه‌ای نباشد که پلتفرم بتواند پنج موضوع را استنباط کند، پلتفرم ممکن است گزینه‌هایی مانند تولید تصادفی موضوعات باقی‌مانده را در نظر بگیرد.

رمزگذاری موضوعات برگشتی

پلتفرم‌های فناوری تبلیغات ثبت‌شده که API موضوعات را فراخوانی می‌کنند، ملزم به ارائه کلیدهای رمزگذاری نیز هستند تا اطمینان حاصل شود که موضوعات برگردانده‌شده فقط برای تماس‌گیرنده قابل خواندن هستند.

Privacy Sandbox این کلیدها را از نقطه پایانی ارائه شده توسط فناوری تبلیغات دریافت می‌کند. ما به عنوان بهترین روش توصیه می‌کنیم که کلیدها به طور منظم به‌روزرسانی شوند، اما نه حداقل هر شش ماه یکبار.

Privacy Sandbox از تکنسین‌های تبلیغات می‌خواهد که در طول فرآیند ثبت‌نام، در دسترس بودن نقطه پایانی ارائه شده را تأیید کنند. برای جزئیات بیشتر در مورد اقدامات مورد نیاز تکنسین‌های تبلیغات فعلی و جدید، به راهنمای ثبت‌نام مراجعه کنید.

Next steps

Implement Topics

Check out implementation details and code samples for callers to observe and access topics.

Control & transparency

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.

See also

Check out our resources to better understand the Topics API on Android.

• Check out Topics sample apps, collab and walkthrough videos.
• See how users and developers can control the API.
• Check out the support resources to ask questions, engage and share feedback.