10 Ara 2025·7 dk
3'ten 30'a ölçeklenen entegrasyon dizini tasarımı
Basit bir veri modeli, net durumlar, izinler ve kurulum ilerleme UI'siyle 3'ten 30 entegrasyona ölçeklenen bir entegrasyon dizini tasarlayın.
Basit bir veri modeli, net durumlar, izinler ve kurulum ilerleme UI'siyle 3'ten 30 entegrasyona ölçeklenen bir entegrasyon dizini tasarlayın.
Kullanıcılar bir entegrasyon dizinini tek bir nedenle açarlar: araçları bağlamak ve her gün onlar hakkında düşünmeden çalışmaya devam etmelerini sağlamak. Ekran kullanıcıların neyin bağlı olduğunu, neyin bozuk olduğunu veya bir sonraki hangi düğmeye tıklanacağını kestirmesine neden oluyorsa, güven hızla düşer.
3 entegrasyonla basit bir logo ızgarası işe yarayabilir. 30 olduğunda işe yaramaz: kullanıcılar taramayı bırakır, destek talepleri artar ve “Connect” düğmesi tuzağa dönüşür çünkü her entegrasyon farklı bir durumda olabilir.
Her entegrasyon kartı (veya satırı) bir bakışta üç soruyu cevaplamalıdır:
Çoğu kafa karışıklığı, gerçek ekiplerde sürekli meydana gelen uç durumlardan gelir. Biri Google'ı şirket hesabı yerine kişisel hesapla bağlar. Bir Stripe token'ı süresi dolar ve faturalama senkronu durur. Bir Slack workspace bağlıdır ama gerekli kanal izni hiç verilmemiştir; bu yüzden kurulum “yarım” görünüyor olabilir ama UI düzgün görünür.
İyi bir ekran bu durumları açık hale getirir. Sadece “Connected” demek yerine “Connected (izin gerekiyor)” veya “Connected to: [email protected]” gösterin ve kart üzerinde sonraki adımı koyun. Bu, insanların tahmine dayalı iş yapmasını engeller ve liste büyüdükçe yönetilebilir kalmasını sağlar.
Entegrasyon dizinini ölçeklendirmenin en basit yolu şunları ayırmaktır:
Bu, 3 entegrasyonda okunabilir kalır ve 30'da da işe yarar.
Bir Integration katalog girdisidir. Küreseldir, herhangi bir workspace'e bağlı değildir.
Bir Install o Integration'ın bir workspace tarafından etkinleştirilmesini temsil eder (örneğin: “Workspace A için Slack açık”).
Bir Connection gerçek bir harici hesap veya kimlik bilgisini temsil eder (örneğin: “Slack workspace X via OAuth” veya “Stripe account Y via API key”). Bir Install birden fazla Connection içerebilir.
Aşağıdaki minimal alan seti genellikle iyi ölçeklenir:
Kullanıcıya gösterilen yapılandırma (seçilen kanal, webhook URL takma adı, etkin olaylar) Install veya Connection üzerinde düz veri olarak saklanabilir. Sırlar (OAuth refresh tokenları, API anahtarları, signing secret'lar) yalnızca bir secrets store'da veya sıkı erişim kontrolleriyle şifrelenmiş bir alanda saklanmalıdır.
Sırları, tam yetkilendirme kodlarını veya ham webhook payloadlarını loglara koymayın. Bir şey loglamanız gerekiyorsa, connection_id gibi referanslar ve güvenli meta veriler (HTTP durum, hata kodu) kaydedin.
OAuth, API anahtarı ve webhook'lara esnek kalmak için auth-özel alanları Connection içinde tutun (token metadata vs anahtar parmak izi vs webhook doğrulama durumu). UI'ya yönelik durum (etkin ve kurulum ilerlemesi) Install üzerinde tutun.
Kullanıcılar bir entegrasyon dizinini açtıklarında üç şeyi hızlıca öğrenmek ister: çalışıyor mu, kurulum ne kadar ileride ve bir sonraki adım ne. Durum kelimeleriniz belirsizse destek talepleri artar ve güven düşer.
Yıllarca tutabileceğiniz küçük bir durum setiyle başlayın:
Saklanan etiket yerine türetilmiş durumu tercih edin. Saklanan etiketler sürüklenir: biri hatayı düzeltir ama rozet kırmızı kalır. Türetilmiş durum, zaten izlediğiniz gerçeklerden hesaplanır; örneğin tokenların geçerli olup olmadığı, gerekli kurulum adımlarının tamamlanıp tamamlanmadığı veya bir admin tarafından entegrasyonun duraklatılıp duraklatılmadığı gibi. Bir şeyi saklıyorsanız, son başarılı senkronizasyon, son hata kodu gibi temel gerçekleri saklayın; nihai etiketi değil.
Kurulum ilerlemesi kısa bir kontrol listesi olarak en iyi çalışır ve gerekli ile isteğe bağlı arasındaki ayrımı net tutar. Bunu entegrasyon başına statik adım tanımları + install başına adım sonuçları olarak modelleyin.
Örnek: Slack için “Workspace yetkilendir” ve “Kanalları seç” zorunlu olabilir; “Mesaj önizlemelerini etkinleştir” isteğe bağlı olabilir. UI “3 zorunlu adımın 2'si tamamlandı” diyebilirken isteğe bağlı öğeleri engelleyici olmadan keşfedilebilir tutar.
Bir entegrasyon altında birden fazla connection, planlamazsanız dizini karıştırabilir. Kart başına bir tane tutun, connection sayısını gösterin ve durumu dürüstçe özetleyin. Herhangi bir connection bozuksa “Needs attention” gösterin ve “4 workspace'in 1'i yeniden yetkilendirme gerektiriyor” gibi bir ipucu verin. Genel görünüm temiz kalır ama gerçekliği yansıtır.
Entegrasyon izinleri her şey bir anahtar gibi ele alındığında karışır. Şunu ayırmak daha nettir:
Hafif bir rol kontrolüyle başlayın. Birçok uygulama için üç rol yeterlidir: Admin, Manager ve Member. Adminler her şeyi yapabilir. Managerlar ekipleri için çoğu entegrasyonu kurabilir. Memberlar zaten etkinleştirilmiş entegrasyonları kullanabilir ama ayarları değiştiremez.
Sadece önemli entegrasyonlar için entegrasyon başına izin bayrakları ekleyin. Çoğu entegrasyon (takvim, sohbet) varsayılan rol kurallarını takip edebilir. Hassas olanlar (ödeme, bordro, dışa aktarımlar) ekstra bir kontrol gerektirsin: “Payments admin” veya “Billing manager”. Bunu tüm yeni bir rol sistemi yerine install üzerinde basit bir boolean olarak tutun.
Okunabilir kalan bir eşleme:
Denetim ağır olmak zorunda değil, ama var olmalı. Destek ve güvenlik sorularını hızlıca yanıtlayacak kadar izleyin: kim bağladı, kimlik bilgileri ne zaman değişti, kim devre dışı bıraktı. Detay sayfasında 5–20 son etkinliği gösteren bir “Activity” paneli genellikle yeterlidir.
Örnek: Stripe herkesin görebildiği ama sadece Adminlerin (veya “Billing manager” olarak işaretlenenlerin) bağlayabileceği, anahtarları döndürebileceği veya ödemeleri devre dışı bırakabileceği şekilde yapılandırılabilir. Slack, Managerların bağlamasına izin verebilirken Memberlar etkinleştirildiğinde bildirim alabilir ama yönetemez.
3 entegrasyonla her şeyi gösterebilirsiniz. 30 ile dizin şu soruyu hızlıca yanıtlamalı: “Hangi entegrasyonlar çalışıyor ve bir sonraki adım ne?” En temiz yaklaşım taramayı (scan) eylemlerden ayırmaktır.
Dizin görünümünü hızlı kararlar için odaklayın. Daha ağır kontrolleri tek bir “Manage” düğmesinin arkasına itin.
Listede yalnızca bir sonraki tıklamayı destekleyen bilgileri gösterin:
Kart anatomisi önemlidir çünkü kas hafızası oluşturur. Birincil eylem her zaman duruma göre “bir sonraki adım” anlamına gelmeli: Yeni için Connect, yarım için Continue setup, yetki süresi dolduysa Reconnect, her şey sağlamsa Manage. Her kartta iki eşit ağırlıklı düğmeden kaçının; sayfa gürültülü olur.
Örnek:
Boş durumlar rehberlik etmeli, kullanıcıya bir kılavuz yığmamalı:
Bu, 30 entegrasyonla bile sayfayı sakin tutar çünkü her kart: bu nedir, iyi mi ve şimdi ne yapmalıyım sorularını cevaplar.
Dizin listesi kullanıcıları doğru entegrasyona götürür. Detay sayfası onların karar verdiği yerdir: kurmak, düzeltmek veya kapatmak. Backend farklı olsa bile sayfa yapısını her entegrasyon için tutarlı tutun.
Kompakt bir genel bakışla başlayın: entegrasyon adı, tek satırlık açıklama ve açık durum etiketleri (Connected, Needs attention, Disabled). Kullanıcıların ne kadar uzakta olduklarını bilmesi için küçük bir “Setup progress” satırı ekleyin.
Basit bir sihirbaz iyi çalışır: 3–6 adım, her seferinde bir ekran, her zaman “Geri” mevcut. Adımları sade ifadelerle adlandırın (Hesabı bağla, Workspace seç, Senkronlanacak verileri seç, Onayla). Bir adım isteğe bağlıysa bunu açıkça “isteğe bağlı” olarak etiketleyin.
Kurulum duraklatılabiliyorsa, bunu açıkça belirtin: “Daha sonra tamamlayabilirsiniz. Seçimleriniz saklanır.” Bu, kullanıcıların ayrılma korkusunu azaltır.
Connections'ı küçük bir tablo olarak gösterin: hesap adı, bağlayan (kullanıcı), oluşturulma tarihi ve son senkron. “Sonraki senkron” için vaat edilemeyecek kesin zamanlardan kaçının. Bunun yerine sisteminizin gerçekten sağlayabileceği biçimde “Yakında planlandı” veya “Yaklaşık bir saat içinde” gibi ifadeler kullanın.
Riskli eylemleri ana yolun uzağına koyun. Birincil eylemleri üstte (Continue setup, Reconnect) tutun. Disable ve Disconnect’ı sayfanın altında ayrı bir “Danger zone” bölümünde kısa bir etki açıklaması ile koyun. Roller destekleniyorsa bunu tek cümleyle belirtin (“Sadece adminler disconnect edebilir”).
Küçük bir etkinlik günlüğü ekleyin: bağlantı, token yenileme, senkronizasyon hatası gibi son olaylar, zaman damgaları ve kullanıcıların destek biletine kopyalayabileceği kısa hata mesajı.
Entegrasyon eklemek, küçük bir ürün gibi ele alındığında daha kolaydır. Bir listeleme, bağlanma yolu, bağlantının saklanacağı yer ve başarı/başarısızlık için net sonuçlara ihtiyaç duyar.
Entegrasyonu katalogunuza ekleyin ki dizinde hiç kimse bağlamadan önce görünsün. Açık bir ad, kısa açıklama, ikon ve bir veya iki kategori (Messaging, Payments) ekleyin. Kurulum beklentilerini sade sözlerle yazın: “Bir hesap bağlayın” ve “Workspace seçin.” Ayrıca ileride ihtiyaç duyulacakları (OAuth scope'ları, gerekli alanlar, desteklenen özellikler) burada tanımlayın.
Sağlayıcıya en uygun en basit bağlantıyı seçin:
Kullanıcı akışı tamamladığında, bağlantıyı workspace veya hesaba bağlı bir Connection kaydı olarak oluşturun, sadece kullanıcının hesabına değil. Kimlik bilgilerini güvenli şekilde saklayın (diskte şifrele, tam sırları tekrar gösterme). Destek için gereken temel bilgileri kaydedin: sağlayıcı hesap ID'si, oluşturulma zamanı, bağlayan kişi ve hangi izinlerin verildiği.
Hemen basit bir test çalıştırın (Stripe için: hesap bilgilerini çek). Geçerse Connected gösterin ve ilerlemeyi hazır olarak işaretleyin. Kısmen geçtiyse (bağlandı ama eksik izin var) Needs attention olarak işaretleyin ve tam gereken düzeltmeyi gösterin.
Bir net mesaj, bir önerilen eylem ve güvenli bir geri dönüş gösterin. Örneğin: “Stripe'e ulaşılamadı. API anahtarını kontrol edin veya tekrar deneyin.” Bir entegrasyon bozuk olsa bile dizinin kullanılabilir kalmasını sağlayın.
Eğer Koder.ai (koder.ai) üzerine inşa ediyorsanız, önce Planning Mode'da katalogu, kurulum akışını ve durum kurallarını taslaklayıp sonra bu plandan UI ve backend üretmek mümkündür.
Entegrasyonlar sıkıcı nedenlerle başarısız olur. Eğer dizininiz bu nedenleri açıkça açıklayamıyorsa kullanıcılar uygulamanızı suçlar ve destekin elinde hiçbir şey kalmaz.
Hataları gerçek düzeltmelere karşılık gelen kovalar halinde gruplayın: giriş süresi doldu, izin eksik, sağlayıcı kesintide veya rate limit. İç hata kodlarını detaylı tutun ama kullanıcılara gösterilen etiket kısa ve anlaşılır olsun.
Bir şey bozulduğunda mesaj üç şeyi yanıtlamalı: ne oldu, kullanıcı ne yapmalı ve sisteminiz bir sonraki adımda ne yapacak. Örnek: “Slack bağlantısının süresi doldu. Senkronizasyon için yeniden bağlayın. Yeniden bağlandığında sistem otomatik yeniden deneme yapacaktır.” Bu, ham API hatasından daha sakinleştirici ve eyleme geçiricidir.
Kullanıcı düzeltemeyeceği durumlarda otomatik yeniden deneme yapın. Basit bir kural seti yeterlidir:
Durumlar güncelliğini yitirir; tokenları, son senkronu ve dizin rozetiyle uyumlu olduklarını periyodik olarak doğrulayan hafif bir sağlık kontrol işi ekleyin.
Her install için küçük bir olay geçmişi tutun. Tam günlük gerekmez; sadece destek için yeterli kırıntılar: zaman damgası, olay (“token yenilendi”, “senkron başarısız”), kısa neden ve tetikleyen (kullanıcı veya sistem). Destekçilerin neyi neden değiştirdiğini not etmeleri için dahili bir not alanı ekleyin.
Bir dizin birkaç uygulamayı geçince hızla karmaşıklaşır. Amaç basittir: insanların ihtiyaç duyduklarını saniyeler içinde bulmalarını sağlamak ve her kartı açmadan sorunları fark etmelerini kolaylaştırmak.
Önce entegrasyon adı ve kategori üzerinde temel arama ekleyin. Çoğu kullanıcı zaten bildiğini yazar (“Slack”, “Stripe”), bu yüzden isim eşleşmesi fancy sıralamadan daha önemlidir. Kategori araması, yalnızca işi biliniyorsa (payments, messaging) yardımcı olur.
Filtreler gerçek niyeti yansıtmalı. Aşağıdakiler çoğu kullanım durumunu karşılar:
Listeyi düzenlemek için birincil grup seçin ve ona sadık kalın. Kategori gruplaması yüksek sayılarda iyi çalışır (CRM, Payments, Messaging). Popülerlik işe yarayabilir ama sadece kullanıcı tabanınızı yansıtıyorsa; pazarlamayı değil. Pratik varsayılan: en çok kullanılanları önce gösterin, gerisini kategoriye göre gruplayın.
“Herkes her şeyi görmemeli” planınız olmalı. Eğer bir entegrasyon özellik bayrağının veya plan katmanının arkasındaysa, ya çoğu kullanıcı için gizleyin ya da kısa bir sebep ile devre dışı gösterin: “Business plan”. Gri kartlarla dolu bir sayfa görmekten kaçının; ekran bozukmuş gibi hissettirir.
Performansı hızlı tutmak için liste ve detayları ayrı yüklemeler olarak ele alın. Listeyi sayfalandırın veya sanallaştırın ki 30 ağır kartı aynı anda render etmeyin; detaylar sadece açıldığında lazy-load olsun. Dizin özet alanları (Slack: Connected, Google: Needs attention, Stripe: Not set up) gösterirken detay sayfası tam bağlantı geçmişini çeksin.
Pinework adında bir ekip çalışma uygulaması hayal edin. İki rolü var: Admin ve Member. Adminler araçları bağlayıp ayarları değiştirebilir. Memberlar bağlı araçları kullanabilir ama ekleyemez veya kaldıramaz.
Pinework’un entegrasyon dizininde her kart net bir etiket (Connected, Needs setup, Error), kısa bir “ne işe yarıyor” satırı ve “2 of 3 steps” gibi kurulum ilerlemesi gösterir. İnsanlar neyin çalıştığını ve neyin beklemede olduğunu tıklamadan anlayabilir.
Slack bildirimler için kullanılır. Bir Admin Slack açarsa: Durum: Connected, Kurulum: “3 of 3 steps.” Memberlar da Slack’i görür ama ana eylem devre dışı olur ve “Ask an Admin to manage” yazar. Slack bağlantısı koparsa Memberlar neyin bozulduğunu görebilir ama yeniden bağlama kontrollerine erişemez.
Google takvimler için kullanılır. Pinework iki departmanı destekliyorsa birden fazla connection’a izin verir. Google kartı: Status: Connected (2 accounts) gösterir. Altında kısa bir satır “Marketing Calendar” ve “Support Calendar” listeler. Kurulum tamam olabilir; detay sayfası iki ayrı connection gösterir ki Admin yalnızca birini iptal edebilsin.
Stripe faturalama için kullanılır. Yaygın yarım kurulum: hesap bağlı ama webhooks tamamlanmamış. Kart: Status: Needs setup, Progress: “2 of 3 steps” ve “Payments may not sync” gibi bir uyarı gösterir. Detay görünüm kalan adımı açıkça gösterir:
Bu, “bağlı görünüyor ama hiçbir şey çalışmıyor” durumunu önler.
Bir uygulama birkaç entegrasyondan onlarcasına büyüdüğünde dizin genellikle bozulur. Sorunlar nadiren “büyük teknik” şeylerdir. Günlük kafa karıştıran etiketleme ve modelleme hatalarıdır.
Yaygın bir sorun “installed” ile “connected”ı karıştırmaktır. Installed genelde “workspace'te kullanılabilir” anlamına gelir. Connected gerçek kimlik bilgileri olduğu ve verinin akabildiği anlamına gelir. Bunlar karıştığında kullanıcılar hazır görünen bir entegrasyona tıklar ve boşta kalırlar.
Bir diğer hata çok fazla durum durumu icat etmektir. Ekipler basit bir rozette başlar, sonra kenar durumlar ekler: pending, verifying, partial, paused, degraded, blocked, expiring ve daha fazlası. Zamanla bu etiketler tutarsızlaşır çünkü kimse onları düzenli tutmaz. Saklanabilir bir küçük set kullanın: Not connected, Connected, Needs attention gibi.
Gizli izinler de sorun yaratır. Biri bir hesabı bağlar, sonra entegrasyonun beklenenden daha geniş erişime sahip olduğunu keşfeder. Bağlamadan önce kapsamı (scope) görünür kılın ve detay sayfasında da gösterin ki adminler denetleyebilsin.
Birçok uygulama birden fazla bağlantıya ihtiyaç duyar: iki Slack workspace, birkaç Stripe hesabı veya paylaşılan bir Google hesabı ve kişisel hesaplar. “Bir entegrasyon = bir connection” diye sert kodlarsanız ileride çirkin geçici çözümlerle uğraşırsınız.
Planlayın:
Liste görünümünü hafif tutun. Onu loglarla, alan eşlemeleriyle ve uzun açıklamalarla doldurursanız tarama yavaşlar. Listeyi ad, kısa amaç ve kurulum ilerlemesi için kullanın. Geçmiş ve gelişmiş ayarları detay sayfasına koyun.
Ölçeklenebilir bir entegrasyon dizini basit bir modele ve dürüst bir UI'ya dayanır. Kullanıcılar üç soruyu hızlıca yanıtlayabiliyorsa sistem öngörülebilir hisseder: ne bağlı, ne bozuk ve şimdi ne yapmalı?
Yayınlamadan önce kontrol listesi:
Sonraki adım olarak, zaten iyi bildiğiniz üç entegrasyonu uçtan uca modelleyin: bir sohbet aracı (OAuth), Google tarzı bir hesap bağlantısı (scope'larla OAuth) ve bir ödeme aracı (API anahtarı + webhooks). Modeliniz bu üç senaryoyu özel durumlara gerek kalmadan ifade edebiliyorsa, genellikle 30 entegrasyona ölçeklenir.
Kontrol paneli gibi ele alın, pazarlama sayfası gibi değil. Her kart hızlıca entegrasyonun ne işe yaradığını, şu an çalışıp çalışmadığını ve kullanıcının atması gereken tek sonraki adımı göstermeli. Kullanıcıların “bu bağlı mı?” diye öğrenmek için tıklaması gerekiyorsa, dizin büyüdükçe güvenilmez hisseder.
Bir entegrasyon kartının cevabı basit olmalı: “bu nedir”, “sağlıklı mı” ve “şimdi ne yapmalıyım”. Genellikle bu, bir isim ve tek satırlık amaç açıklaması, son zaman damgası ile durum ve duruma göre değişen birincil butondur. Tarama hızlı kalsın diye geri kalan her şey “Manage” altında saklanmalı.
Sunduğunuz şeyi, bir workspace'in etkinleştirdiğini ve hangi kimlik bilgilerinin olduğunu birbirinden ayırın. Küresel bir Integration (katalog girdisi), bir workspace için Install (etkinleştirme) ve gerçek OAuth hesabı, API anahtarı veya webhook için Connection kullanın. Bu, genellikle “yüklü” ile “bağlı”nın karıştığı yaygın karmaşayı önler.
Gerçek ekipler genellikle aynı sağlayıcı için birden fazla harici hesaba ihtiyaç duyar. Marketing ve Support farklı Google takvimleri bağlayabilir veya bir şirketin birden fazla Stripe hesabı olabilir. Bir Install altında birden fazla Connection modellemek dizini temiz tutar ve adminlerin detay sayfasında hesapları tek tek yönetmesine izin verir.
Aşınmayı önlemek için küçük bir etiket seti kullanın: Not set up, In progress, Connected, Needs attention ve Disabled gibi. Ardından bu etiketleri belirli doğrulanabilir gerçeklerden türetin (örneğin token geçerliliği, gerekli adımların tamamlanıp tamamlanmadığı, son başarılı senkronizasyon). Bu, bir sorun çözüldükten sonra kırmızı rozeti orada bırakmaktan kaçınmanızı sağlar.
Kurulum ilerlemesini, engelleyici olmayan isteğe bağlı adımların yanında kısa bir gereklilikler listesi olarak gösterin. Adım tanımlarını entegrasyon başına statik olarak tutun ve her install için adım sonuçlarını saklayın, böylece UI “3 adımın 2’si tamamlandı” diyebilir ve eksik zorunlu adımı doğrudan gösterebilir.
Her yerde uygulanacak basit bir rol kuralı ile başlayın, sonra yalnızca hassas entegrasyonlar için ekstra kontroller ekleyin. Çoğu üründe Adminler her şeyi yapar, Managerlar çoğu entegrasyonu kurabilir, Memberlar etkinleştirilmiş entegrasyonları kullanabilir ama ayarları değiştiremez. Ödemeler veya bordro gibi hassas durumlar için yeni bir rol sistemi yaratmak yerine tek bir “billing/payments admin” bayrağı ekleyin.
Kullanıcıya görünür yapılandırma verilerini normal olarak saklayın; ancak refresh tokenlar ve API anahtarları gibi sırları bir secrets store'da veya sıkı erişim kontrolleri olan şifreli alanlarda tutun. Ham gizli verileri, yetkilendirme kodlarını veya webhook payloadlarını loglamayın; bunun yerine connection ID gibi referanslar ve güvenli meta veriler kaydedin.
Kullanıcıya ne olduğunu, ne yapması gerektiğini ve sisteminizin otomatik olarak ne yapacağını söyleyen bir hata mesajı gösterin. Yeniden denemeler yalnızca kullanıcının düzeltemeyeceği durumlar için sessizce ve sınırlı biçimde olmalı. Auth süresi dolduysa veya izin eksikse, yeniden denemeyi durdurun ve “Reconnect” ya da “Fix permissions” birincil eylem olsun.
Arama basit ve kullanıcıların düşündüğü şekilde olsun: önce sağlayıcı adı, sonra kategori. Filtreler niyeti yansıtmalı: Connected, Needs attention ve Not set up gibi. Eğer Koder.ai üzerinde inşa ediyorsanız, katalog alanlarını, durum kurallarını ve kurulum adımlarını önce Planning Mode'da tasarlayın ki oluşturulan UI ve backend tutarlı kalsın.