Discord User-Installable App: Kullanıcıya Kurulan Uygulama Rehberi

Kurulum bağlamı: GUILD_INSTALL ve USER_INSTALL

Discord belgelerinde buna installation context (kurulum bağlamı) deniyor ve iki değeri var:

• Sunucuya kurulan uygulama: MANAGE_GUILD iznine sahip bir üye tarafından yetkilendirilmelidir. Sunucudaki tüm üyelere görünür; kimin hangi komutu nerede kullanacağını komut izinleri belirler. Kurulumda verilen OAuth2 kapsamları ve bot izinleri, uygulamanın o sunucuda neye erişebileceğini belirler.
• Kullanıcıya kurulan uygulama: yalnızca yetkilendiren kullanıcıya görünür ve sunucuya özel izin gerektirmez. Kullanıcının tüm sunucularında, DM'lerinde ve grup DM'lerinde görünür, ancak kullanıldığı yerde kullanıcının kendi izinlerine uymak zorundadır.

Belgede verilen örnek bu sınırı iyi anlatıyor: kullanıcı, mesaj gönderme izni olmayan bir sunucu kanalında kullanıcıya kurulu bir uygulamanın komutunu çalıştırırsa, uygulama o etkileşime ephemeral olmayan (herkese görünen) bir mesajla yanıt veremez. Ayrıca yalnızca kullanıcıya kurulan uygulamalar bir sunucuda işlem yapamaz; yalnızca sunucuya kurulan uygulamalar da kullanıcının DM'lerinden erişilemez.

Etkileşim bağlamı: GUILD, BOT_DM, PRIVATE_CHANNEL

Komutun Discord istemcisinin hangi yüzeylerinde kullanılabileceğini contexts alanı belirler:

Developer Portal'da kullanıcı kurulumunu açmak

Belgeye göre yeni oluşturulan uygulamalar varsayılan olarak yalnızca sunuculara kurulabilir. Kullanıcı kurulumunu açmak için:

• Developer Portal'da uygulamanızı açın ve soldaki menüden Installation sayfasına gidin.
• Installation Contexts bölümünde User Install ve isterseniz Guild Install kutularını işaretleyip Save Changes deyin.
• Install Link bölümünde bağlantı türünü seçin. Belge çoğu uygulama için "Discord Provided Link" seçeneğini öneriyor.
• "Discord Provided Link" seçiliyken görünen Default Install Settings bölümünde, User Install için applications.commands kapsamını; Guild Install için applications.commands ve bot kapsamlarını ve botun ihtiyaç duyduğu izinleri seçin.
• Kaydettikten sonra kurulum bağlantısını tarayıcıda açın; iki bağlam da açıksa Discord kullanıcıya hangi şekilde kurmak istediğini sorar.

Discord tarafından sağlanan bağlantı, URL'de kapsam ve izin taşımaz; örneğin https://discord.com/oauth2/authorize?client_id=... şeklindedir ve kullanıcıya Default Install Settings'teki ayarları sunar. Bu tür bağlantılar yalnızca applications.commands ve bot kapsamlarıyla sınırlıdır. Kullanıcı kurulumunda varsayılan ayarlar şu an yalnızca applications.commands kapsamını destekler. "None" seçilirse uygulama profilinde "Add App" düğmesi görünmez ve uygulama App Directory için uygun olmaz. Sunucu davet linkinin ayrıntıları botu sunucuya ekleme ve davet linki yazısında.

Örnek komut: her yerde çalışan bir /zar komutu

Önce ham API gövdesine bakalım. Bu komut hem sunucuya hem kullanıcıya kurulumda, üç bağlamın hepsinde kullanılabilir:

{
  "name": "zar",
  "description": "1 ile 6 arasında zar atar",
  "type": 1,
  "integration_types": [0, 1],
  "contexts": [0, 1, 2]
}

discord.js'te komut verisinde integrationTypes ve contexts alanları bulunur. Komut global olarak kaydedilmelidir; yalnızca bir sunucuya kaydedilen komutlarda bu alanlar geçerli değildir:

const {
  Client, Events, GatewayIntentBits, MessageFlags,
  ApplicationIntegrationType, InteractionContextType,
} = require('discord.js');

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

client.once(Events.ClientReady, async (c) => {
  await c.application.commands.create({
    name: 'zar',
    description: '1 ile 6 arasında zar atar',
    integrationTypes: [ApplicationIntegrationType.GuildInstall, ApplicationIntegrationType.UserInstall],
    contexts: [InteractionContextType.Guild, InteractionContextType.BotDM, InteractionContextType.PrivateChannel],
  });
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand() || interaction.commandName !== 'zar') return;
  const sonuc = Math.floor(Math.random() * 6) + 1;
  // Sunucu kanalında sadece kullanıcı görsün, DM'de normal yanıt
  const gizli = interaction.context === InteractionContextType.Guild;
  await interaction.reply({ content: `Zar: ${sonuc}`, flags: gizli ? MessageFlags.Ephemeral : undefined });
});

client.login(process.env.DISCORD_TOKEN);

discord.py 2.x'te aynı ayarlar dekoratörlerle yapılır: app_commands.allowed_installs kurulum bağlamını, app_commands.allowed_contexts etkileşim bağlamını belirler. Kısayol olarak app_commands.user_install() ve app_commands.guild_install() dekoratörleri de vardır.

import random
import discord
from discord import app_commands

@app_commands.command(name='zar', description='1 ile 6 arasında zar atar')
@app_commands.allowed_installs(guilds=True, users=True)
@app_commands.allowed_contexts(guilds=True, dms=True, private_channels=True)
async def zar(interaction: discord.Interaction):
    await interaction.response.send_message(f'Zar: {random.randint(1, 6)}')

Komut kaydı ve senkronizasyonu (tree.sync()) hakkında ayrıntılar için slash komut oluşturma ve discord.py ile bot yapımı yazılarına bakabilirsiniz.

Etkileşimde bağlamı anlamak: context ve authorizing_integration_owners

Kullanıcıya kurulu bir uygulamada gelen etkileşimin nereden geldiğini anlamak için üç alan önemlidir:

• context: komutun çalıştırıldığı etkileşim bağlamı (0, 1 veya 2). Kendi botunuzla olan DM BOT_DM'dir; aynı komutu bir arkadaşınızla olan DM'de çalıştırırsanız bağlam PRIVATE_CHANNEL olur.
• authorizing_integration_owners: etkileşimin hangi kurulumlar üzerinden yetkilendirildiğini gösterir. Anahtar "1" (USER_INSTALL) ise değer uygulamayı kuran kullanıcının ID'sidir. Anahtar "0" (GUILD_INSTALL) ise değer sunucudan geldiyse sunucu ID'si, bot DM'inden geldiyse "0"'dır.
• app_permissions: uygulamanın etkileşimin geldiği yerdeki izinleri. Belgeye göre başka kullanıcılarla olan (grup) DM'lerde bu değer ATTACH_FILES, EMBED_LINKS ve MENTION_EVERYONE izinlerini içerir; botun kendi DM'inde ayrıca USE_EXTERNAL_EMOJIS eklenir.

Kullanıcıya kurulu uygulamada neler kısıtlı?

Pratikte bu şu anlama gelir: uygulama bir sunucuya ayrıca kurulmadıkça o sunucuda işlem yapamaz; elindeki kanal, kullanıcının çalıştırdığı komut etkileşimi ve buna verdiği yanıttır. Bu yüzden kullanıcı kurulumu; zar, hatırlatıcı, çeviri, profil kartı, arama gibi kişisel araçlar için uygundur. Moderasyon gibi sunucu yetkisi gereken işler için uygulama sunucuya da kurulmalıdır (bkz. AutoMod ve moderasyon botu).

Sık Sorulan Sorular

User install ile bot sunucuya eklenmiş olur mu?

Hayır. Kullanıcı kurulumu uygulamayı yalnızca o kullanıcının hesabına ekler ve yalnızca o kullanıcıya görünür. Sunucuya kurulmayan bir uygulama o sunucuda işlem yapamaz; sunucu yetkisi gereken işler için uygulamanın Guild Install ile ayrıca sunucuya eklenmesi gerekir.

Arkadaşımla DM'de komut kullanabilir miyim?

Evet, uygulama hesabınıza kuruluysa ve komutun integration_types listesinde USER_INSTALL, contexts listesinde PRIVATE_CHANNEL (2) varsa.

Komutum DM'de neden görünmüyor?

Kontrol listesi: uygulamanın Installation sayfasında User Install açık mı, komut global olarak mı kayıtlı, integration_types ve contexts alanları doğru mu, uygulama hesabınıza kurulu mu? Yeni bir bağlam eklediyseniz var olan komutları da güncellemeniz gerekir.

Kullanıcıya kurulu uygulama embed veya dosya gönderebilir mi?

Etkileşim yanıtlarında gönderebilir. Belgeye göre başka kullanıcılarla olan DM'lerde uygulamanın izinleri ATTACH_FILES ve EMBED_LINKS içerir. Embed hazırlamak için embed mesaj oluşturma rehberine bakın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Slash komut oluşturma · Etkileşim başarısız oldu hatası · HTTP interactions ve Cloudflare Workers · Botu sunucuya ekleme ve davet linki · Discord uygulama premium abonelik · OAuth2 ve OIDC rehberi