Docs Dashboard

Quick Start Guide

Animal Skill

The Animal skill is a simple example of how to easily create a skill. The skill identifies an animal and expands your search by finding additional information about the animal on Bing.

Before creating a skill be sure to review our developer agreement and skill certification rules and policies.

Create your skill

Tell us a little about your skill by giving it a skill name, author and description. End-users will see these fields when your skill is triggered in the skill store and/or a search result.

Build your skill

1. Build a custom visual intent query: If animals

  • Select Custom Triggers
  • Add Animals as a trigger
  • 2. Image Metadata

  • Select Annotations
  • 3. Service URL

    Your service URL should be any https endpoint that Bing can communicate with. Feel free to use a service that works for your skills needs.

    For the sake of this quick start guide we will use a C#/Javascript Azure function. (How to create an azure function)

    Copy & paste the code below into your Azure function/service.

                                
    #r "Newtonsoft.Json"
    using System.Net;
    using Newtonsoft.Json;
    using Newtonsoft.Json.Linq;
    
    //A simple class to hold the skill CustomData that is expected to be returned
    public class CustomData
    {
        public string previewText = String.Empty;
        public string imageUri = String.Empty;
        public string clickthroughUri = String.Empty;
    }
    
    
    public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
    {
        HttpResponseMessage httpResponse = null;
    
        try
        {
    
            //Skill request should be JSON in the incoming request
            string skillsRequest = await req.Content.ReadAsStringAsync();
    
            //parse the JSON
            var requestJson = JObject.Parse(skillsRequest);
    
            //Incoming requests contains various Image metadata that the skill has requested
            //like Visual Intents, Annotations, Image blob, OCR text, etc. 
            //consult the Request JSON schema documentation for more info.
    
            //Here, lets extract the first annotation, if present.        
            //JsonPath to the annotations. Refer to Skill request JSON schema for more info.
            string annotationsJsonPath = "$.imageInfo.recognitionModels[?(@.modelName == 'ImageAnnotationV2')].results[0].categories[*].name";
    
            var annotations = requestJson.SelectTokens(annotationsJsonPath);
    
            if (annotations.Any()) //we have at leat 1 annotation
            {
    
                string firstAnnotation = annotations.First().ToString();
    
                //construct sample skill response
    
                //preview text is a short blurb that shows up in the app when user invokes the skill
                string previewText = $"Look, a {firstAnnotation}!";
    
                //thumbnail to show with the preview. In this case we will show a static bing logo but could be response specific thumbnail
                string bingThumbnail = "https://c.s-microsoft.com/en-us/CMSImages/BingLogo.png?version=23e74020-f1ba-f831-f846-04a1ba5959ed";
    
                //A click through Url that users will navigate to. In this skill, we do a bing search on the first annotation            
                string searchUri = $"https://www.bing.com/images/search?q={firstAnnotation}";
                searchUri = System.Uri.EscapeUriString(searchUri); //escape the string just in case annotation contains special chars
    
                //fill the customdata object with our response info
                CustomData myCustomData = new CustomData();
                myCustomData.previewText = previewText;
                myCustomData.imageUri = bingThumbnail;
                myCustomData.clickthroughUri = searchUri;
    
                string skillProviderName = "Bing Visual Skills SDK - Animal";
    
                //construct the skill response object we are required to return.
                //Review the Skills Response JSON schema documentation for more info.
                var skillResponse = new
                {
                    results = new[]
                    {
                        new {
                            tags = new [] {
                                new {
                                    actions = new [] {
                                        new {
                                            actionType = "Custom",                  //This is required to be set to "Custom"
                                            customData = myCustomData,              //Set to custom data object
                                            providerName = skillProviderName        //The skill name as provider name
                                       }
                                    },
                                    sources = new [] {skillProviderName}
                                }
                            }
                        }
                    }
                };
    
                //construct a "200 OK" HTTP response with the above payload. 
                httpResponse = req.CreateResponse(HttpStatusCode.OK,
                                                  skillResponse,
                                                  "application/json");
            }
            else
            {
                log.Info("No annotations detected. Returning '204 No Content' http response");
    
                httpResponse = req.CreateResponse(HttpStatusCode.NoContent);
            }
        }
        catch (Exception ex)
        {
            log.Error(ex.Message);
    
            httpResponse = req.CreateResponse(HttpStatusCode.BadRequest);
        }
    
        return httpResponse;
    }
                                    
                                

    Copy & paste your Azure function/service URL into the service URL field and click save

    4. Test Image Metadata

  • Sample Images
  • Save these images to help test your skill.

  • Drag and drop your test images on the file uploader and click Upload . The first image in the list will be selected by default and image metadata for the selected image will load in the pane below.
  • Click on each of the uploaded images to see the image metadata results.
  • 5. Test your service

    • Click the Run button to send your service the image metadata of the test image you have selected. You will see the JSON returned from your service in the code pane below

    6. Preview your skill result

    • A preview of the skill result will be automatically generated from JSON returned by your service. Users will see this result when your skill is triggered.

    Test and Share your skill

    Before you test your skill in the Bing iOS app, you should set up your skill preview by providing two things:

    1. A skill icon that best represents your skill
    2. A preview image that users will see as a sample when they try out your skill

    Use the file uploaders to add these files.

    You will see your skill preview which is a sample of what users will see in the Bing iOS app.

    Follow the instructions on How to test your skill using the Test Code in the Bing iOS app and share it with your friends to try out.