Bot BağlayıcıSı API'siyle iletilere zengin kart ekleri ekleme
Bazı kanallar botunuzun kullanıcılara zengin kartlar göndermesine izin verir. Zengin kart, düğmeler, metin, resimler, ses, video gibi etkileşimli öğeler içeren bir ektir.
Bu makalede, bir iletiye ekleyebileceğiniz zengin kartların nasıl oluşturulacağı açıklanır. İletiye ek eklemeyle ilgili belirli yönergeler için iletilere medya eklerinin nasıl ekleneceğini öğrenin.
Zengin kart türleri
Zengin kart 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 zengin kart türünü 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. Kanal başına desteğe bakın. |
| AnimationCard | 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. |
| ThumbnailCard | 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ını sağlayan kart. Genellikle makbuza, vergiye, toplam bilgiye ve diğer metne 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 kartlar içindeki 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 | string | bu eylemle ilişkili kanala özgü veriler |
| displayText | string | düğmeye tıklandığında sohbet akışında görüntülenmesini test etme |
| metin | string | eylem metni |
| tür | string | eylem türü (aşağıdaki tabloda belirtilen değerlerden biri) |
| başlık | string | düğmenin başlığı |
| image | string | düğmenin resim URL'si |
| değer | string | 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, bunun yerine 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 eyleminin messageBack diğer kart eylemlerinden daha genelleştirilmiş bir anlamı vardır. ve diğer kart eylem türleri hakkında daha fazla bilgi için Etkinlik şemasınınmessageBack Kart eylemi bölümüne bakın.
| Tür | Açıklama | Değer |
|---|---|---|
| çağrısı | Bir telefon araması başlatır. | Telefon araması için hedef şu biçimdedir: tel:123123123123. |
| Downloadfile | Bir dosyayı 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 | Bir video oynatır. | Yürütülecek videonun URL'si. |
| Geri gönderme | 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. |
| Imzalıyorum | 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.- Kartını temsil etmek için kendi
contentoluşturduğunuz nesneye özelliğini 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ırtmaları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 Activity nesnesinin attachmentLayout özelliğini "list" olarak ayarlayın.
Döngü biçiminde birden çok zengin kart görüntülemek için nesnenin ActivityattachmentLayout özelliğini "döngü" olarak ayarlayın.
Kanal döngü biçimini desteklemiyorsa, özellik "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 isteklerin temel URI'sini temsil eder. 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 bileşim ve karmaşıklık kartları oluşturmak için kullanılabilecek JSON örneklerini görmek için Uyarlamalı Kartlar sitesindeki bilgilerden yararlanın. Ayrıca, Uyarlamalı Kart yükleri 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 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ğuyla ilgili bilgiler (onların adı ve avatarı), kartın ne zaman oluşturulduğu, iş ödevlerinin 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:
