رویدادهای server-to-server

رویدادها را مستقیماً از سرور خود با استفاده از S2S Event API به Adtrace ارسال کنید. رویدادهای S2S در پنل مثل رویدادهای SDK نمایش داده می‌شوند.

SDK صف‌بندی، تلاش مجدد و تحویل سمت کلاینت را مدیریت می‌کند، بنابراین رویدادهای معمول درون‌برنامه‌ای را تا حد امکان از طریق SDK ارسال کنید. از S2S برای رویدادهای حساس یا اعتبارسنجی‌شده سمت سرور استفاده کنید: نه برای هر رویداد در اپ.

نصب الزامی است

قبل از پذیرش هر رویداد S2S، دستگاه باید یک نصب ثبت‌شده داشته باشد. ابتدا Adtrace SDK را روی Android، iOS یا Web یکپارچه کنید، سپس رویدادهای انتخابی را از سرور خود ارسال کنید.

مهم

قبل از ارسال رویدادهای S2S، وجود نصب دستگاه را در Testing Console در پنل تأیید کنید.

ارسال درآمد گذشته یا جمع‌بندی‌شده

می‌توانید رویدادهای S2S را هر زمان پس از وجود نصب برای یک دستگاه ارسال کنید.

موضوع	رفتار
نصب	باید از قبل برای آن دستگاه وجود داشته باشد.
زمان رویداد	به طور پیش‌فرض، timestamp زمانی که Adtrace درخواست را دریافت می‌کند است.
`sent_at`	مقدار اختیاری ISO 8601 اگر به زمان رویداد خاصی نیاز دارید.
Backfill تاریخی	می‌توانید درآمد گذشته جمع‌بندی‌شده را در یک فراخوانی ارسال کنید، اما ردیف‌های رویداد تاریخی جداگانه را بازسازی نمی‌کند مگر اینکه درخواست‌های جداگانه با مقادیر `sent_at` مناسب ارسال کنید.

Endpoint


URL	`https://s2s.adtrace.io/s2s/event`
Method	`POST`
Content-Type	`application/json`
Authorization	`Token <S2S API KEY>`

کلید S2S API خود را از پنل Adtrace (Dashboard → Settings) دریافت کنید.

فیلدهای رایج بدنه درخواست

فیلد	الزامی	توضیحات
`app_token`	بله	توکن اپ شما از پنل. مثال: `abc123xyz456`
`event_token`	بله	توکن رویداد شما از پنل. مثال: `xyz123`
`os_name`	بله*	`"android"` یا `"ios"` برای موبایل. برای شناسه‌های وب به Web مراجعه کنید.
`revenue`	خیر	مقدار درآمد به صورت رشته. مثال: `"5000000"`
`currency`	خیر	برچسب ارز. هنگام تنظیم `revenue` الزامی است. مثال: `"IRR"`
`sent_at`	خیر	timestamp رویداد در ISO 8601. مثال: `2024-01-01T01:01:01.001Z+0000`
`event_value_params`	خیر	پارامترهای رویداد به صورت JSON string. مثال: `"{\"key1\":\"value1\"}"`

* رویدادهای Web ممکن است از web_uuid بدون os_name استفاده کنند: به بخش Web زیر مراجعه کنید.

هر درخواست باید یک شناسه دستگاه پلتفرم داشته باشد. همه شناسه‌ها را حذف نکنید.

Android

os_name را برابر "android" (حروف کوچک) تنظیم کنید.

فیلد	الزامی	توضیحات
`gps_adid`	یکی الزامی*	Google Play Services advertising ID.
`adtrace_adid`	یکی الزامی*	شناسه دستگاه Adtrace (`adid`). هنگامی که `gps_adid` در دسترس نیست استفاده کنید.

شناسه‌ها را از Android SDK یا Testing Console بخوانید.

مثال (Android)

curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
  --header 'Authorization: Token YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_token": "YOUR_APP_TOKEN",
    "os_name": "android",
    "gps_adid": "DEVICE_GPS_ADID",
    "event_token": "YOUR_EVENT_TOKEN",
    "revenue": "5000000",
    "currency": "IRR"
  }'

مثال با `adtrace_adid` (Android)

curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
  --header 'Authorization: Token YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_token": "YOUR_APP_TOKEN",
    "os_name": "android",
    "adtrace_adid": "DEVICE_ADTRACE_ADID",
    "event_token": "YOUR_EVENT_TOKEN"
  }'

iOS

os_name را برابر "ios" (حروف کوچک) تنظیم کنید.

فیلد	الزامی	توضیحات
`idfa`	یکی الزامی*	Apple Identifier for Advertisers. فقط هنگامی در دسترس است که کاربر ردیابی را مجاز کرده باشد.
`adtrace_adid`	یکی الزامی*	شناسه دستگاه Adtrace (`adid`). هنگامی که `idfa` در دسترس نیست استفاده کنید.

شناسه‌ها را از iOS SDK یا Testing Console بخوانید.

مثال (iOS)

curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
  --header 'Authorization: Token YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_token": "YOUR_APP_TOKEN",
    "os_name": "ios",
    "idfa": "DEVICE_IDFA",
    "event_token": "YOUR_EVENT_TOKEN",
    "revenue": "9.99",
    "currency": "USD"
  }'

مثال با `adtrace_adid` (iOS)

curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
  --header 'Authorization: Token YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_token": "YOUR_APP_TOKEN",
    "os_name": "ios",
    "adtrace_adid": "DEVICE_ADTRACE_ADID",
    "event_token": "YOUR_EVENT_TOKEN"
  }'

Web

برای یکپارچه‌سازی‌های وب، web_uuid یا adid را به عنوان شناسه دستگاه ارسال کنید. web_uuid را با Adtrace.getWebUUID() بازیابی کنید و آن را به backend خود ارسال کنید.

فیلد	الزامی	توضیحات
`web_uuid`	یکی الزامی*	شناسه دستگاه وب از Web SDK.
`adid`	یکی الزامی*	شناسه دستگاه Adtrace از attribution. هنگامی که `web_uuid` در دسترس نیست استفاده کنید.

مثال (Web)

curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
  --header 'Authorization: Token YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "app_token": "YOUR_APP_TOKEN",
    "web_uuid": "DEVICE_WEB_UUID",
    "event_token": "YOUR_EVENT_TOKEN"
  }'

برای راهنمایی خاص وب، به FAQ وب: رویدادهای S2S مراجعه کنید.

عیب‌یابی

وضعیت	خطا	اقدام
404	`Install for device not found`	هیچ رکورد نصبی وجود ندارد. اپ یا سایت را باز کنید تا SDK یک نصب ارسال کند، سپس در Testing Console تأیید کنید.
404	`Device ids not found`	یک شناسه دستگاه پلتفرم (`gps_adid`، `idfa`، `web_uuid` یا `adtrace_adid`) وارد کنید.
403	`IP address is not valid`	IP سرور خود را به IP allowlist در پنل اضافه کنید. برای تأیید IP خروجی، `curl ident.me` را روی سرور اجرا کنید.
400	`Os name must be android or ios`	`os_name` را دقیقاً `"android"` یا `"ios"` (حروف کوچک) برای درخواست‌های موبایل تنظیم کنید.

ارسال درآمد گذشته یا جمع‌بندی‌شده​

Endpoint​

فیلدهای رایج بدنه درخواست​

Android​

مثال (Android)​

مثال با adtrace_adid (Android)​

iOS​

مثال (iOS)​

مثال با adtrace_adid (iOS)​

Web​

مثال (Web)​

عیب‌یابی​

مطالب مرتبط​