Bot Bağlayıcısı API'siyle iletilere zengin kart ekleri ekleme
Bazı kanallar botunuzun kullanıcılara zengin kartlar göndermesine olanak tanır. Zengin kart, düğmeler, metin, resimler, ses, video vb. gibi etkileşimli öğeler içeren bir ektir.
Bu makalede, iletiye ekleyebileceğiniz zengin kartların nasıl oluşturulacağı açıklanmaktadır. İletiye ek eklemeyle ilgili belirli yönergeler için bkz. iletilere medya ekleri ekleme.
Zengin kart türleri
Zengin kart bir başlık, açıklama, bağlantı ve görüntülerden oluşur. İleti, liste biçiminde veya döngü biçiminde görüntülenen birden çok zengin kart içerebilir. Bot Framework şu anda sekiz tür zengin kartı destekler:
| Kart türü | Açıklama |
|---|---|
| AdaptiveCard | Metin, konuşma, resim, düğme ve giriş alanlarının herhangi bir bileşimini içerebilen özelleştirilebilir bir kart. Bkz. kanal başına destek. |
| Animasyon Kartı | Animasyonlu GIF'leri veya kısa videoları oynatabilen bir kart. |
| AudioCard | Ses dosyasını yürütebilen bir kart. |
| HeroCard | Genellikle tek bir büyük resim, bir veya daha fazla düğme ve metin içeren bir kart. |
| Küçük Resim Kartı | Genellikle tek bir küçük resim görüntüsü, bir veya daha fazla düğme ve metin içeren bir kart. |
| ReceiptCard | Botların kullanıcıya makbuz sağlamasına olanak tanıyan kart. Genellikle makbuz, vergi ve toplam bilgileri ve diğer metinlere eklenecek öğelerin listesini içerir. |
| SignInCard | Botun kullanıcının oturum açmasını istemesini sağlayan kart. Genellikle kullanıcının oturum açma işlemini başlatmak için tıklayabileceği metin ve bir veya daha fazla düğme içerir. |
| VideoCard | Video oynatabilen bir kart. |
İpucu
Her kanalda hangi özelliklerin desteklendiği hakkında bilgi için kanal başvurusu makalesine bakın.
Zengin kartlarda olayları işleme
Zengin kartlarda olayları işlemek için CardAction nesnelerini kullanarak kullanıcı bir düğmeye tıkladığında veya kartın bir bölümüne dokunduğunda ne olacağını belirtin. Her CardAction nesne şu özellikleri içerir:
| Özellik | Türü | Açıklama |
|---|---|---|
| channelData | Dize | bu eylemle ilişkili kanala özgü veriler |
| displayText | Dize | düğmeye tıklandığında sohbet akışında görüntülenecek şekilde test edin |
| text | Dize | eylem metni |
| Tür | Dize | eylem türü (aşağıdaki tabloda belirtilen değerlerden biri) |
| başlık | Dize | düğmenin başlığı |
| görüntü | Dize | düğmenin resim URL'si |
| değer | Dize | belirtilen eylem türünü gerçekleştirmek için gereken değer |
Not
Uyarlamalı Kartlar içindeki düğmeler nesneler kullanılarak CardAction değil, Uyarlamalı Kartlar tarafından tanımlanan şema kullanılarak oluşturulur.
Uyarlamalı Karta düğmelerin nasıl ekleneceğini gösteren bir örnek için bkz . İletiye Uyarlamalı Kart ekleme.
Düzgün çalışması için, bir hero kartındaki her tıklanabilir öğeye bir eylem türü atayın. Bu tabloda kullanılabilir eylem türleri ve ilişkili değer özelliğinde olması gerekenler listelenip açıklanmaktadır.
Kart messageBack eylemi, diğer kart eylemlerinden daha genelleştirilmiş bir anlama sahiptir. ve diğer kart eylem türleri hakkında daha fazla bilgi için Etkinlik şemasının messageBack Kart eylemi bölümüne bakın.
| Type | Açıklama | Değer |
|---|---|---|
| call | Bir telefon araması başlatır. | Telefon aramasının hedefi şu biçimdedir: tel:123123123123. |
| downloadFile | Bir dosya indirir. | İndirilmesi gereken dosyanın URL'si. |
| imBack | Bota bir ileti gönderir ve sohbette görünür bir yanıt gönderir. | Gönderilecek iletinin metni. |
| messageBack | Sohbet sistemi aracılığıyla gönderilecek metin yanıtını temsil eder. | Oluşturulan iletilere eklenecek isteğe bağlı bir program değeri. |
| openUrl | Yerleşik tarayıcıda bir URL açar. | Açılacak URL. |
| playAudio | Ses çalar. | Yürütülecek sesin URL'si. |
| playVideo | Video yürütülür. | Yürütülecek videonun URL'si. |
| postBack | Bota bir ileti gönderir ve sohbette görünür bir yanıt göndermeyebilir. | Gönderilecek iletinin metni. |
| showImage | Bir resim görüntüler. | Görüntülenecek görüntünün URL'si. |
| oturum açma | OAuth oturum açma işlemini başlatır. | Başlatacak OAuth akışının URL'si. |
İletiye Hero kartı ekleme
İletiye zengin kart eki eklemek için:
- İletiye eklemek istediğiniz kart türünü temsil eden bir nesne oluşturun.
- Ek nesnesi oluşturma:
contentTypeÖzelliğini kartın medya türüne ayarlayın.- özelliğini
content, kartı temsil etmek için oluşturduğunuz nesneye ayarlayın.
Attachmentnesnesini ileti dizisineattachmentsekleyin.
İpucu
Zengin kart ekleri içeren iletiler genellikle belirtmez text.
Bazı kanallar, bir iletinin içindeki diziye birden çok zengin kart eklemenize attachments olanak tanır. Bu özellik, kullanıcıya birden çok seçenek sağlamak istediğiniz senaryolarda yararlı olabilir. Örneğin, botunuz kullanıcıların otel odaları ayırmasına izin veriyorsa, kullanıcıya kullanılabilir oda türlerini gösteren zengin kartların listesini sunabilir. Her kart, oda türüne karşılık gelen bir resim ve olanak listesi içerebilir ve kullanıcı bir karta dokunarak veya bir düğmeye tıklayarak bir oda türü seçebilir.
İpucu
Birden çok zengin kartı liste biçiminde görüntülemek için Etkinlik nesnesinin attachmentLayout özelliğini "list" olarak ayarlayın.
Döngü biçiminde birden çok zengin kart görüntülemek için nesnenin Activity attachmentLayout özelliğini "döngü" olarak ayarlayın.
Kanal döngü biçimini desteklemiyorsa, özelliği "döngü" belirtse attachmentLayout bile zengin kartları liste biçiminde görüntüler.
Aşağıdaki örnekte tek bir Hero kart eki içeren eksiksiz bir ileti gösterilmektedir. Bu örnek istekte temel https://smba.trafficmanager.net/teams URI'yi temsil eder; bot sorunlarınızın farklı olabileceği istekler için temel URI. Temel URI'yi ayarlama hakkında ayrıntılı bilgi için bkz . API Başvurusu.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "sender's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "recipient's name"
},
"attachments": [
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "title goes here",
"subtitle": "subtitle goes here",
"text": "descriptive text goes here",
"images": [
{
"url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"alt": "picture of a duck",
"tap": {
"type": "playAudio",
"value": "url to an audio track of a duck call goes here"
}
}
],
"buttons": [
{
"type": "playAudio",
"title": "Duck Call",
"value": "url to an audio track of a duck call goes here"
},
{
"type": "openUrl",
"title": "Watch Video",
"image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"value": "url goes here of the duck in flight"
}
]
}
}
],
"replyToId": "5d5cdc723"
}
İletiye Uyarlamalı kart ekleme
Uyarlamalı Kart metin, konuşma, resim, düğme ve giriş alanlarının herhangi bir bileşimini içerebilir. Uyarlamalı Kartlar, Uyarlamalı Kartlar'da belirtilen JSON biçimi kullanılarak oluşturulur ve bu da kart içeriği ve biçimi üzerinde tam denetim sağlar.
Uyarlamalı Kart şemasını anlamak, Uyarlamalı Kart öğelerini keşfetmek ve çeşitli kompozisyon ve karmaşıklıkta kartlar oluşturmak için kullanılabilecek JSON örneklerini görmek için Uyarlamalı Kartlar sitesindeki bilgilerden yararlanın. Ayrıca, Uyarlamalı Kart yüklerini tasarlamak ve kart çıkışını önizlemek için Etkileşimli Görselleştirici'yi kullanabilirsiniz.
Aşağıdaki örnekte, bir iş atamasını temsil eden tek bir Uyarlamalı Kart ek nesnesi gösterilmektedir. Bunu bir kullanıcıya göndermek için, bunu iletiye ek olarak eklemeniz gerekir.
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Publish Adaptive Card schema",
"weight": "bolder",
"size": "medium"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"size": "small",
"style": "person"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Matt Hidinger",
"weight": "bolder",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "none",
"text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
"isSubtle": true,
"wrap": true
}
]
}
]
}
]
},
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Card"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Comment",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Text",
"id": "comment",
"isMultiline": true,
"placeholder": "Enter your comment"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
]
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
]
}
Sonuçta elde edilen kartta bir başlık, kartı kimin oluşturduğu hakkında bilgiler (onların adı ve avatarı), kartın ne zaman oluşturulduğu, iş atamalarının açıklaması ve ödevle ilgili bilgiler bulunur. Ayrıca, iş atamasına açıklama eklemek veya görüntülemek için tıklanabilir düğmeler de vardır:
