---
title: "ردیابی Telegram Ads: ماکروها و postback تبدیل"
description: "نحوه ردیابی کمپین‌های Telegram Ads در AdsGram: ماکروها برای لینک‌های وب، postback تبدیل از طریق API تأیید تبدیل و رویدادهای خودکار Goal 1 برای Mini App، ربات و کانال."
outline: [2,4]
---
# ردیابی Telegram Ads
برای ردیابی دقیق‌تر عملکرد کمپین‌های Telegram Ads و انتساب صحیح منابع اقدامات هدف، توصیه می‌شود از یک **سیستم آنالیتیکس** استفاده کنید.

## ماکروهای پشتیبانی‌شده برای لینک‌های وب در Telegram Ads
برای ردیابی دقیق، از ماکروها استفاده کنید. AdsGram آن‌ها را به‌طور خودکار با داده‌های واقعی در لینک ردیابی شما جایگزین می‌کند.
- `{campaign_id}`
- `{banner_id}`
- `{publisher_id}`
- `{useragent}`
- `{click_id}`
- `{ip}`
- `{campaign}` — نام کمپین

> [!IMPORTANT] مهم
> این پشتیبانی فقط برای لینک‌های وب در Telegram Ads اعمال می‌شود. ماکروهای AdsGram همچنان برای لینک‌هایی که به Telegram Mini Apps (TMA)، ربات‌ها یا کانال‌های Telegram در کمپین‌های Telegram Ads منتهی می‌شوند پشتیبانی نمی‌شوند.

::: warning هشدار
برای اینکه API تأیید تبدیل با لینک‌های وب در کمپین‌های Telegram Ads به‌درستی کار کند، URL کمپین باید ماکرو `{campaign_id}` را داشته باشد. اگر ماکرو الزامی وجود نداشته باشد، ردیابی تبدیل کار نخواهد کرد.

در کمپین‌های Telegram Ads، ماکروهای AdsGram برای لینک‌هایی که به Telegram Mini Apps (TMA)، ربات‌ها یا کانال‌ها منتهی می‌شوند پشتیبانی نمی‌شوند. بنابراین از API تأیید تبدیل نمی‌توان برای ردیابی تبدیل‌های چنین لینک‌هایی در کمپین‌های Telegram Ads استفاده کرد. برای اطلاعات بیشتر، بخش [ردیابی تبدیل برای لینک‌های داخل Telegram در کمپین‌های Telegram Ads](#ردیابی-تبدیل-برای-لینک‌های-داخل-telegram-در-کمپین‌های-telegram-ads) را در پایین ببینید.
:::

> [!IMPORTANT] مهم
> ماکرو `{publisher_id}` فقط به‌عنوان شناسه منحصربه‌فرد ناشر آشکار می‌شود — بدون ذکر نام یا سایر اطلاعات شناسایی.

نمونه URL کمپین:
```
https://your-tracker.com/?campaign={campaign_id}&banner={banner_id}&pub={publisher_id}&clickid={click_id}
```

پنل ماکروهای اضافه‌شده به لینک <img src="../../images/icons/added_macros.png" alt="Added macros" width="18" style="display: inline" /> و مواردی که وجود ندارند <img src="../../images/icons/missed_macros.png" alt="Missed macros" width="18" style="display: inline" /> را برجسته می‌کند.

![ماکروهای انتخاب‌شده](../../advertiser/images/selected_macroses.webp =500x)

## راه‌اندازی postback تبدیل برای لینک‌های وب در Telegram Ads
### پارامترها:
- `token` — یک توکن منحصربه‌فرد مرتبط با حساب شما. این توکن در پنل AdsGram در دسترس است و در صورت نیاز قابل بازتولید است.

  **نحوه دریافت توکن:**
  1. پنل AdsGram را باز کنید.
  1. روی پروفایل خود در گوشه بالا سمت راست کلیک کنید.
  1. پارامتر `token` را پیدا کنید و برای کپی کردن آن روی دکمه کپی <img src="../../images/icons/copy.png" alt="Copy" width="18" style="display: inline" /> کلیک کنید.

  ![Copy macros](../../advertiser/images/copy_macros.webp =200x)
- `campaignid` — شناسه کمپین تبلیغاتی AdsGram که تبدیل به آن تعلق دارد. با مقدار ماکروی `{campaign_id}` که در لینک تبلیغاتی ارسال می‌شود مطابقت دارد. AdsGram هنگام کلیک کاربر روی لینک، مقدار ماکرو را جایگزین می‌کند.
- `goaltype` — پارامتری که نوع تبدیل (مرحله قیف) را مشخص می‌کند و به بخش‌بندی اقدامات مختلف کاربر کمک می‌کند. مقادیر صحیح از ۱ تا ۳ را می‌پذیرد.

  ##### نحوه استفاده از goaltype:
  1. مراحل قیف را در محصول یا سرویس خود تعریف کنید.
  1. مراحل را به مقادیر goaltype نگاشت کنید:
      - ۱. ثبت‌نام
      - ۲. اولین واریز/خرید
      - ۳. واریز/خرید مجدد
  1. ردیابی تبدیل را برای مراحل مربوطه سفر کاربر پیکربندی کنید.
  1. پارامتر goaltype را به درخواست API خود هنگام ارسال داده‌های تبدیل اضافه کنید.
  1. از این پارامتر در آنالیتیکس خود برای انجام تحلیل عملکرد دقیق بر اساس نوع تبدیل استفاده کنید.

### نحوه راه‌اندازی ردیابی تبدیل:
1. **یک کمپین Telegram Ads انتخاب کنید.** از یک کمپین فعال موجود استفاده کنید یا کمپین جدیدی بسازید.
1. **لینک ردیابی را پیکربندی کنید.** مطمئن شوید که ماکروی `{campaign_id}` را دارد.
1. **توکن خود را دریافت کنید.** توکن منحصربه‌فرد خود را از پنل AdsGram کپی کنید.
1. **ارسال postback را تنظیم کنید.** سرور خود را طوری پیکربندی کنید که هر بار کاربر یک اقدام هدف را انجام می‌دهد، یک درخواست API به AdsGram بفرستد.
1. **نوع تبدیل را مشخص کنید.** اگر می‌خواهید مراحل قیف را از هم تفکیک کنید، مقدار مناسب `goaltype` را تنظیم کنید.
1. **یکپارچه‌سازی را آزمایش کنید.** مراحل بخش **آزمایش یکپارچه‌سازی** در پایین را دنبال کنید و مطمئن شوید تبدیل‌ها در آمار AdsGram نمایش داده می‌شوند.

#### نمونه درخواست API هنگام تبدیل:
```
GET
https://api.adsgram.ai/confirm_conversion?token=YOUR_UNIQUE_TOKEN&campaignid=72156&goaltype=2
```
در این مثال، `goaltype=2` نشان‌دهنده تبدیلی مانند اولین واریز یا خرید است.

`YOUR_UNIQUE_TOKEN` را با توکن حساب خود و `72156` را با شناسه کمپین تبلیغاتی خود جایگزین کنید.

**پاسخ مورد انتظار:** `200 OK` — تبدیل با موفقیت ثبت شد.

### آزمایش یکپارچه‌سازی
برای آزمایش ردیابی تبدیل، این مراحل را دنبال کنید:
1. **یک کمپین بسازید یا انتخاب کنید.** یک کمپین Telegram Ads بسازید یا انتخاب کنید و لینک ردیابی را مطابق مستندات پیکربندی کنید. مطمئن شوید که ماکروی `{campaign_id}` در لینک وجود دارد.
1. **منتظر کلیک‌ها بمانید.** صبر کنید تا کاربران چند بار روی لینک ردیابی کلیک کنند.
1. **به‌صورت دستی یک postback آزمایشی با پارامتر `goaltype=1` ارسال کنید.** از یک `token` معتبر و شناسه کمپین آزمایشی در پارامتر `campaignid` استفاده کنید.
1. **نتیجه را بررسی کنید.** مطمئن شوید که درخواست با موفقیت پردازش شده و تبدیل در آمار AdsGram برای کمپین انتخاب‌شده نمایش داده می‌شود.

### عیب‌یابی
- **تبدیل در آمار نمایش داده می‌شود:** یکپارچه‌سازی به‌درستی پیکربندی شده و برای سناریوی آزمایش‌شده کار می‌کند.
- **سرور خطا برمی‌گرداند:** URL درخواست و مقادیر پارامترهای `token`، `campaignid` و `goaltype` را بررسی کنید.
- **درخواست موفق است، اما تبدیل نمایش داده نمی‌شود:** آمار هر یک ساعت یک بار به‌روزرسانی می‌شود. اگر پس از یک ساعت تبدیل هنوز نمایش داده نشد، با پشتیبانی AdsGram یا مدیر حساب خود تماس بگیرید و حتماً لاگ‌های درخواست و پاسخ را پیوست کنید.

## ردیابی تبدیل برای لینک‌های داخل Telegram در کمپین‌های Telegram Ads
در کمپین‌های Telegram Ads، ماکروهای AdsGram برای لینک‌هایی که به مقصدهای داخل Telegram می‌روند پشتیبانی نمی‌شوند و به این لینک‌های تبلیغاتی منتقل نمی‌شوند. بنابراین API تأیید تبدیل را نمی‌توان برای ردیابی تبدیل‌های لینک‌هایی که به Telegram Mini Apps (TMA)، ربات‌ها یا کانال‌ها می‌روند استفاده کرد.

برای لینک‌های داخل Telegram در کمپین‌های Telegram Ads، رویدادهای هدف زیر به‌طور پیش‌فرض و خودکار در **Goal 1** ثبت می‌شوند:
- TMA — اجرای TMA؛
- ربات‌ها — اجرای ربات؛
- کانال‌ها — عضویت در کانال.

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