Telegram Yerleşik Analitiği

Telegram, benzersiz bağlantılar kullanarak reklam yerleşimlerinin sonuçlarını analiz etmek için araçlar sunar. Her reklam yerleşimi için ayrı bir bağlantı oluşturabilirsiniz. Kanallar ve gruplar için katılım istatistikleri doğrudan Telegram'da bulunur; botlar ve Mini App'ler için ise bağlantı parametrelerinin kaydedilmesini ve veri toplamayı ayrıca projeniz tarafında yapılandırmanız gerekir.

DİKKAT

Bir reklam yerleşimi = bir benzersiz bağlantı. Aynı bağlantı birden fazla reklamda kullanılırsa trafik kaynakları karışır ve sonradan ayrılamaz.

Bu analitik türü, AdsGram kampanya istatistiklerinden ve dönüşüm takibinden ayrı çalışır.

Bölüm 1. Reklamveren tarafındaki kampanya yöneticileri için

1. Hangi bağlantıyı kullanmalısınız?

Farklı reklam yerleşimlerinin sonuçlarını karşılaştırmak için her biri için benzersiz bir bağlantı kullanın.

Örneğin bir projeyi üç Telegram kanalında tanıtıyorsanız, üç ayrı bağlantı oluşturun. Böylece hangi yerleşimlerin daha fazla kullanıcı getirdiğini belirleyebilirsiniz.

Bağlantı türü, reklamın nereye yönlendirdiğine bağlıdır:

Reklam hedefi	Bağlantı biçimi	Sonuçların takip edileceği yer
Telegram kanalı veya grubu	Ayrı bir davet bağlantısı	Telegram: kanal veya grup ayarları → Invite links
Bot	t.me/YourBot?start=ad_sep_anna	Parametreyi kaydediyorsa botunuz
Mini App	t.me/YourBot?startapp=ad_sep_anna	Parametreyi kaydediyorsa uygulamanızın sunucusu

YourBot yerine botunuzun kullanıcı adını, ad_sep_anna yerine reklam yerleşimi için benzersiz bir parametre yazın.

2. Kanallar ve gruplar: davet bağlantıları

Her reklam yerleşimi için ayrı bir davet bağlantısı oluşturun.

1. Kanalı veya grubu açın ve adına dokunun.
2. Düzenleme veya yönetim ayarlarını açın. Masaüstü sürümünde ⋮ → Manage channel / Manage group yolunu kullanabilirsiniz.
3. Invite links bölümünü açın ve yeni bağlantı oluşturma seçeneğini seçin.
4. Bağlantıya yerleşime uygun bir ad verin, örneğin ad_sep_anna. Ad yalnızca yöneticilere görünür, bağlantıyı açan kullanıcılara görünmez.
5. Gerekirse bir son kullanma tarihi, kullanıcı sınırı belirleyin veya yönetici onayını zorunlu kılın.
6. Bağlantıyı yalnızca bir reklam yerleşiminde kullanın.

İstatistikler nerede görülür: Telegram'ın Invite links ekranı, her bağlantı üzerinden kaç kullanıcının katıldığını gösterir. Kullanıcı listesini görmek için ilgili bağlantıyı açın.

t.me/yourchannel gibi normal bir genel bağlantı, katılımları reklam yerleşimine göre ayırmanıza izin vermez. Herkese açık kanallar da davet bağlantısı oluşturabilir; bu nedenle reklamlarınızda ayrı davet bağlantıları kullanın.

3. Botlar: start parametreli bağlantılar

Şu bağlantı biçimini kullanın:

https://t.me/<bot>?start=<parameter>

Örneğin:

https://t.me/YourBot?start=ad_sep_anna

Kullanıcı bağlantıyı açıp Start düğmesine bastığında bot, parametreyi içeren bir komut alır:

/start ad_sep_anna

Telegram, bu bot başlatmaları için reklam atribüsyonunu otomatik olarak raporlamaz. Bot, kullanıcı kaydı ilk kez oluşturulduğunda parametreyi kaydetmelidir.

Metriğiniz yeni kullanıcı edinimiyse yalnızca yeni kullanıcıları sayın. Mevcut bir kullanıcının reklam bağlantısını açması onu yeni kullanıcı yapmaz.

4. Mini App'ler: startapp parametreli bağlantılar

Bir botun ana Mini App'i için şunu kullanın:

https://t.me/<bot>?startapp=<parameter>

@BotFather içinde /newapp ile oluşturulan bir Mini App için şunu kullanabilirsiniz:

https://t.me/<bot>/<app>?startapp=<parameter>

Örneğin:

https://t.me/YourBot?startapp=ad_sep_anna

Gerekirse bir görüntüleme modu parametresi ekleyin:

• &mode=compact — kompakt mod.
• &mode=fullscreen — tam ekran modu.

Mini App, parametreyi start_param alanında alır. Uygulamanızın sunucusu, kullanıcı uygulamayı ilk kez başlattığında bunu kaydetmelidir.

Kullanıcı Mini App'i bir reklam bağlantısı olmadan açarsa — örneğin menü düğmesi veya bot profili üzerinden — reklam parametresi bulunmayabilir. Başka güvenilir bir atribüsyon kaynağı yoksa bu başlatmayı organik kabul edin.

5. Parametre kuralları

• Maksimum uzunluk:

  • start parametresi — 64 karakter
  • startapp parametresi — 512 karakter

• İzin verilen karakterler:

  • A-Z, a-z, 0-9, _, -
  • Boşluk, Kiril karakterleri veya nokta kullanmayın. Uyumluluk sorunlarını önlemek için izin verilen karakter kümesine bağlı kalın.

• Parametrelere kullanıcıların kişisel verilerini eklemeyin.

• Önerilen adlandırma şablonu. Yerleşimlerin raporlarda kolayca bulunabilmesi için tutarlı bir biçim kullanın: ad_<month>_<source>_<creative>

  Örnekler:

  • ad_sep_tgads_video1
  • ad_sep_blogger_anna

6. Kampanya bağlantıları referans bağlantıları değildir

Referans bağlantısı, kullanıcının başka kişileri davet etmesini ve ödül almasını sağlar.

Reklam bağlantısı, bir reklam yerleşiminden gelen trafiği ölçer. Tek başına bir referans ödülünü tetiklememelidir.

İki türü öneklerle ayırın:

• ref_… — kullanıcı referans bağlantıları.
• ad_… — reklam yerleşimi bağlantıları.

Her reklam kampanyası için ayrı bir referans bağlantısı oluşturmak yalnızca geçici bir çözümdür. Bu, reklam trafiği için referans ödülleri ödenmesine ve istatistiklerin karışmasına yol açabilir.

7. Tıklamalar nasıl sayılır

Telegram, t.me bağlantıları için tıklama istatistiği sağlamaz.

Tıklamaları saymanız gerekiyorsa kullanıcıları önce kendi yönlendirmenizden geçirin, ardından Telegram'a gönderin.

Örnek:

https://yourdomain.com/go/ad_sep_anna → https://t.me/YourBot?start=ad_sep_anna

Sunucunuz tıklamayı kaydeder ve kullanıcıyı hedef bağlantıya yönlendirir. Bu, kendi uygulamanızı gerektirir ve başlatmaların, yeni kullanıcıların veya kanal katılımlarının takibinin yerini tutmaz.

8. Sonuç tablosu tutma

Her benzersiz bağlantı için bir satır içeren bir tablo oluşturun.

Önerilen sütunlar:

Alan	Ne kaydedilmeli
Bağlantı parametresi	Örneğin, ad_sep_anna
Yerleşim	Kanal, gönderi, influencer veya reklam adı
Tarihler	Yerleşim dönemi
Harcama	Reklam maliyeti
Yeni kullanıcılar	Bağlantıya atfedilen yeni kullanıcı sayısı
Kullanıcı başına maliyet	Harcama ÷ yeni kullanıcı sayısı

9. Yayın öncesi kontrol listesi

Bir reklamı yayınlamadan önce şunlardan emin olun:

• Her yerleşimin kendi bağlantısı var; bağlantılar başka yerleşimlerde yeniden kullanılmıyor.
• Parametre maksimum uzunluğu aşmıyor ve yalnızca izin verilen karakterleri içeriyor.
• Bağlantı ikinci bir hesapla test edildi: katılım sayılıyor veya parametre bot ya da Mini App tarafından kaydediliyor.
• Bağlantı, yerleşim adı ve harcama tabloya eklendi.

Bölüm 2. Geliştiriciler için uygulama

Aşağıdaki örneklerde Python, SQL ve bot için aiogram 3 kullanılmıştır. Aynı ilkeler başka teknolojilerle de uygulanabilir.

Kod, hazır ve eksiksiz bir entegrasyon değil, bir temel sunar. Veritabanı erişim fonksiyonları ve bazı entegrasyon ayrıntıları uygulamanıza göre uyarlanmalıdır.

10. Hangi veriler saklanmalı

Atribüsyon için üç varlık gerekir:

1. Reklam bağlantıları ve kampanyalar kaydı.
2. Kullanıcı kaydı oluşturulurken saklanan kullanıcı edinme kaynağı.
3. Mevcut kullanıcıların ziyaretleri dahil, kampanya bağlantısı ziyaretlerinin geçmişi.

Örnek SQL şeması:

-- Her reklam bağlantısı için bir satır.
-- Örneğin, "ad_sep_anna" parametresi "sep_anna" koduna karşılık gelir.
CREATE TABLE campaigns (
    code       text PRIMARY KEY,
    name       text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
);

-- Kullanıcının edinme kaynağı oluşturulurken belirlenir.
-- NULL organik anlamına gelir.
ALTER TABLE users
ADD COLUMN campaign text REFERENCES campaigns (code);

-- Kampanya bağlantılarını açan tüm kullanıcılar,
-- yeni ve mevcut kullanıcılar dahil.
CREATE TABLE campaign_visits (
    code     text REFERENCES campaigns (code),
    user_id  bigint,
    first_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (code, user_id)
);

code alanı, sep_anna gibi kısa bir kampanya kodu içermelidir. name alanı yerleşimi tanımlar, örneğin Anna'nın kanalı, eylül gönderisi.

campaign_visits tablosu, ziyaretleri kullanıcının ilk edinme kaynağından ayrı olarak takip eder. Kullanıcı her başka bağlantı açtığında ilk kaynak üzerine yazılmamalıdır.

11. Parametreleri ayrıştırma: bot ve Mini App için tek ayrıştırıcı

Reklam ve referans parametreleri için tek bir ayrıştırıcı kullanın.

import re

AD = re.compile(r"ad_([A-Za-z0-9_-]{1,61})")
REF = re.compile(r"ref_([A-Za-z0-9]{4,32})")


def parse_start(param: str | None) -> tuple[str, str] | None:
    """("ad", code), ("ref", code) veya diğer her durumda None."""
    if not param:
        return None

    if m := AD.fullmatch(param):
        return "ad", m[1]

    if m := REF.fullmatch(param):
        return "ref", m[1]

    return None

Ayrıştırmadan sonra elde edilen kodun campaigns tablosunda olup olmadığını kontrol edin.

• Bilinmeyen bir kodu mevcut bir kampanyaya atfetmeyin. Bu ziyareti organik veya atfedilmemiş kabul edin.
• Doğrulanmamış ham parametre değerlerini saklamayın.
• Bot ve Mini App tarafından alınan parametrelere aynı ayrıştırma kurallarını uygulayın.

12. Bot: /start işleme

Kullanıcı bir botu başlattığında Telegram, parametreyi /start komutunun argümanlarında iletir.

aiogram 3 ile örnek:

@router.message(CommandStart())
async def start(message: Message, command: CommandObject):
    source = parse_start(command.args)
    # "/start ad_sep_anna" -> ("ad", "sep_anna")

    async with db.transaction():
        await create_user_if_new(message.from_user, source)

        if source and source[0] == "ad":
            await record_visit(source[1], message.from_user.id)

create_user_if_new fonksiyonu, yalnızca kullanıcı henüz yoksa kullanıcı kaydı oluşturmalıdır.

Yinelenen kayıtları önlemek için şu gibi atomik bir işlem kullanın:

-- create_user_if_new: atomik, bot ve Mini App aynı anda istek gönderdiğinde güvenli
INSERT INTO users (id, campaign, referrer_id)
VALUES ($1, $2, $3)
ON CONFLICT (id) DO NOTHING
RETURNING id; -- bir satır döndü = yeni kullanıcı; hiçbir şey dönmedi = mevcut kullanıcı, olduğu gibi bırakıldı

Sorgu bir satır döndürürse kullanıcı oluşturulmuştur. Hiç satır döndürmezse kullanıcı zaten vardır ve ilk edinme kaynağı değişmeden kalmalıdır.

Kampanya bağlantısı ziyaretini kaydetmek için şunu kullanın:

-- record_visit
INSERT INTO campaign_visits (code, user_id)
VALUES ($1, $2)
ON CONFLICT DO NOTHING;

Mevcut bir kullanıcı başka bir bağlantı açar ve /start ad_… alırsa ziyareti kaydedin, ancak campaign alanının üzerine yazmayın.

Referans atribüsyonu için referrer_id değerini yalnızca yeni kullanıcılar için ayarlayın. Kullanıcıların kendilerini referans göstermesine izin vermeyin.

13. Mini App: ilk başlatmayı işleme

Bir Mini App, start_param parametresini Telegram Web App başlatma verilerinin bir parçası olarak alabilir.

Frontend tarafında Telegram'ın imzaladığı verileri sunucunuza gönderin:

// Frontend: her istek Telegram tarafından imzalanmış başlatma verilerini taşır
fetch("/api/me", { headers: { Authorization: `tma ${Telegram.WebApp.initData}` } })

Sunucuda, kullanıcı kimliğini veya start_param değerini kullanmadan önce initData verisinin gerçekliğini ve yaşını doğrulayın.

Python'da örnek doğrulama fonksiyonu:

import hashlib, hmac, json, time
from urllib.parse import parse_qsl


def check_init_data(
    raw: str,
    bot_token: str,
    max_age: int = 86400
) -> dict:
    fields = dict(
        parse_qsl(
            raw,
            keep_blank_values=True,
            strict_parsing=True
        )
    )

    received = fields.pop("hash", "")
    # hash dışındaki tüm alanlar, "signature" dahil, sıralanmış, her satırda bir key=value
    data = "\n".join(
        f"{k}={v}" for k, v in sorted(fields.items())
    )

    secret = hmac.new(
        b"WebAppData",
        bot_token.encode(),
        hashlib.sha256
    ).digest()

    expected = hmac.new(
        secret,
        data.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, received):
        raise PermissionError("bad signature")

    if time.time() - int(fields["auth_date"]) > max_age:
        raise PermissionError("expired")

    return {
        "user": json.loads(fields["user"]),
        "start_param": fields.get("start_param")
    }

Doğrulama başarılı olduktan sonra bottaki ile aynı süreci izleyin (create_user_if_new ve record_visit):

1. Doğrulanmış verilerden user ve start_param değerlerini alın.
2. Parametreyi parse_start ile ayrıştırın.
3. Kullanıcıyı yalnızca henüz yoksa oluşturun.
4. Parametre bilinen bir reklam kampanyasıyla eşleşiyorsa kampanya bağlantısı ziyaretini kaydedin.

Güvenlik: yalnızca doğrulanmış initData kullanın. initDataUnsafe veya URL parametrelerine kullanıcı kimliği ya da atribüsyon kaynağı olarak güvenmeyin; bunlar sahte olabilir.

start_param parametresi, uygulama ilgili bağlantı üzerinden başlatıldığında iletilir. Menüden yapılan sonraki başlatmalarda bulunmayabilir. Bu nedenle ilk edinme kaynağını her uygulama başlatmasında değil, kullanıcı oluşturulurken belirleyin.

14. Bir kullanıcı, iki giriş noktası

Bot ve Mini App, her kullanıcının Telegram user ID ile tanımlandığı tek bir users tablosunu paylaşabilir.

Örneğin bir kullanıcı önce botu başlatıp sonra Mini App'i açabilir veya tam tersini yapabilir.

Atribüsyon kuralları:

• Kullanıcı kaydını ilk oluşturan handler, ilk edinme kaynağını belirler.
• İkinci handler bu kaynağın üzerine yazmamalıdır.
• Sonraki ziyaretler campaign_visits içinde ayrıca kaydedilebilir.

INSERT … ON CONFLICT DO NOTHING gibi atomik bir ekleme kullanın. Bu, bot ve Mini App'ten gelen istekler neredeyse aynı anda ulaştığında hataları önlemeye yardımcı olur.

15. Kanallar: davet bağlantısına göre katılım takibi

Yalnızca Telegram arayüzüne güvenmek yerine kendi katılım takibinize ihtiyacınız varsa, her kampanya için ayrı bir davet bağlantısı oluşturun ve kampanya koduyla birlikte kaydedin.

Python'da bağlantı oluşturma örneği:

# Her kampanya için bir bağlantı oluşturun ve kodla birlikte saklayın
link = await bot.create_chat_invite_link(
    CHANNEL_ID,
    name="ad_sep_anna"
)  # ad: 1–32 karakter
save_channel_link("ad_sep_anna", link.invite_link)

Bu örnekte davet bağlantısının adı 1–32 karakterle sınırlıdır.

Katılım olaylarını almak için bot, kanalın yöneticisi olmalı ve ilgili chat_member güncellemelerini almalıdır. Katılım istekleri onay gerektiriyorsa chat_join_request güncellemelerini de almalıdır.

Örnek polling yapılandırması:

# Katılımlar chat_member güncellemeleri olarak gelir: bot yönetici olmalı ve bunları talep etmelidir
await dp.start_polling(
    bot,
    allowed_updates=[
        "message",
        "chat_member",
        "chat_join_request"
    ]
)

Örnek katılım handler'ı:

@router.chat_member()
async def member(update: ChatMemberUpdated):
    joined = (
        update.old_chat_member.status in ("left", "kicked")
        and update.new_chat_member.status == "member"
    )

    if joined and update.invite_link:
        save_channel_join(
            update.invite_link.name,
            update.new_chat_member.user.id
        )

Bir bağlantı yönetici onayı gerektiriyorsa chat_join_request olayını işleyin. Davet bağlantısı update.invite_link içinde bulunur; isteği kontrol ettikten sonra approve_chat_join_request çağırabilirsiniz.

Kimlerin kanalda kaldığını anlamak için kullanıcıların kanaldan ayrılmalarını da kaydedebilirsiniz.

Telegram, yöneticilere her davet bağlantısı için katılım sayısını zaten gösterir. Kanal katılım verilerini bot kullanıcı bilgileri veya diğer analitiklerle birleştirmek istiyorsanız kendi veritabanınız işe yarar.

16. İsteğe bağlı: yönlendirme ile tıklama takibi

Kullanıcılar Telegram'a ulaşmadan önce tıklamaları saymak için kendi yönlendirme endpoint'inizi oluşturun.

Mini App için Python örneği:

@app.get("/go/{code}")
async def go(code: str, request: Request):
    agent = request.headers.get("user-agent", "")

    if code_exists(code) and "TelegramBot" not in agent:  # Telegram'ın bağlantı önizleme tarayıcısını yok say
        record_click(code)

    return RedirectResponse(
        f"https://t.me/{BOT}?startapp=ad_{code}",
        status_code=302
    )

Bu örnek kodu doğrular ve User-Agent değerinde TelegramBot bulunan istekleri hariç tutar; böylece Telegram'ın bağlantı önizleme istekleri normal kullanıcı tıklaması olarak sayılmaz.

Uygulamayı altyapınıza göre uyarlayın ve gerçek bağlantılarla test edin. Yönlendirme, uygun parametreyle doğru bot veya Mini App bağlantısına gitmelidir.

17. Örnek rapor

Aşağıdaki sorgu her kampanya için benzersiz kampanya bağlantısı ziyaretçilerinin, yeni kullanıcıların ve etkinleştirilmiş kullanıcıların sayısını gösterir.

SELECT
    c.code,
    c.name,
    (
        SELECT count(*)
        FROM campaign_visits v
        WHERE v.code = c.code
    ) AS visitors,
    (
        SELECT count(*)
        FROM users u
        WHERE u.campaign = c.code
    ) AS new_users,
    (
        SELECT count(*)
        FROM users u
        WHERE u.campaign = c.code
          AND u.first_action_at IS NOT NULL
    ) AS active
FROM campaigns c
ORDER BY new_users DESC;
-- first_action_at: kullanıcının kampanyanın ödeme yaptığı eylemi ilk kez gerçekleştirdiği zaman (görev, satın alma)

Bu örnekte first_action_at, kullanıcının reklamverenin ödeme yaptığı hedef eylemi (örneğin bir görevi tamamlama veya satın alma) ilk kez gerçekleştirdiği zamandır.

visitors metriği, campaign_visits içinde ilgili kampanyaya kayıtlı ziyareti olan kullanıcıları ifade eder. Tıklamalar bir yönlendirme ile ayrıca kaydedilmedikçe bağlantı tıklama sayısına eşit değildir.

18. Sık yapılan hatalar ve sınırlamalar

• Bot, parametreyi yalnızca kullanıcı Start düğmesine bastığında alır. Bağlantıya tıklayan herkes botu başlatmaz; bu nedenle başlatma sayısı tıklama sayısından az olabilir.
• Yeniden başlatma yeni kullanıcı anlamına gelmez. Kullanıcı sohbeti silip botu yeniden başlatırsa parametre tekrar iletilebilir, ancak kullanıcı yeni değildir.
• İlk edinme kaynağının üzerine yazmayın. Sonraki ziyaretleri analiz etmek için zaman damgalı ayrı bir ziyaret tablosu kullanın.
• Yeni ve mevcut hesapları ayırın. Amaç edinimse tekrarlanan ziyaretler yeni kullanıcı sayısını artırmamalıdır.
• Botları ve kendi kendine referansları hariç tutun. is_bot değerini kontrol edin ve kullanıcıların kendilerini referans göstermesine izin vermeyin.
• Parametre sınırlarına uyun. start parametresinin toplam uzunluğu 64 karakteri geçmemelidir. ad_ veya ref_ önekine yer bırakmak için sep_anna gibi kısa kodlar kullanın.
• Referans ve reklam atribüsyonunu ayrı tutun. Farklı önekler ve işleme kuralları, hatalı ödülleri ve raporları önlemeye yardımcı olur.