Import a Scalable Vector Graphic (SVG) (Beta)

Use the APL authoring tool to convert Scalable Vector Graphics (SVG) files into Alexa Vector Graphics (AVG) objects to use in your Alexa Presentation Language (APL) documents.

The SVG format is an XML-based markup language for describing vector graphics. AVG is a parameterized subset of SVG. You can display an AVG-defined graphic in your document with the VectorGraphic component.

Convert an SVG file to AVG in the authoring tool

You can convert an SVG to an AVG in one of two ways:

• Import an SVG into an existing APL document
• Create a new APL document from the SVG

In both cases, the import does the following:

• Adds an (AVG) to the graphics property of the document. The AVG contains the converted data from the SVG. For details about the AVG format, see Alexa Vector Graphics Format.
• Adds a VectorGraphic component in mainTemplate that displays the AVG.

After the import, you can move the component to the correct place to display. For example, you might move the component into a Container.

You can import files that use SVG version 1.1. For details about SVG format, see the MDN documentation. See Supported features for the features of SVG the converter supports.

To import an SVG file into an existing APL document

1. In the authoring tool, open the APL document you want to edit.
2. In the toolbar, click either APL or GRAPHICS.

3. Select the GUI View tab, and then click Add Component.

   

4. In the Add Component dialog box, select Vector Graphic.
5. In the Select an Option drop-down list, select Convert from SVG.
6. Either drag your SVG file to the Select SVG File box, or click Browse and locate the file to import.
7. If necessary, change the New Graphic Name.
   • The name defaults to the file name of your SVG file, but you can change it if necessary.
   • The new AVG in the graphics map uses the name you provide.
8. Click Add.

The authoring tool adds the new VectorGraphic component to the end of the mainTemplate array in your document. If your mainTemplate contains other components, you won't see any change in the document preview. Move the VectorGraphic component into your Container or to the top of mainTemplate to see the graphic.

The following example shows an APL document that displays AlexaHeadline, the Text, and a VectorGraphic in a Container.

Document example: VectorGraphic within a container  

{
  "type": "APL",
  "version": "2024.3",
  "license": "Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License  http://aws.amazon.com/asl/",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100%",
        "width": "100%",
        "items": [
          {
            "type": "AlexaHeader",
            "headerTitle": "Scalable Vector Graphics (SVG) Example",
            "headerSubtitle": "You can convert an SVG to an Alexa Vector Graphics (AVG)"
          },
          {
            "type": "Text",
            "text": "This is a Text component inside a Container",
            "padding": [
              "@marginHorizontal",
              "@spacingSmall"
            ]
          },
          {
            "source": "heartGraphicExample",
            "type": "VectorGraphic"
          }
        ]
      }
    ]
  },
  "layouts": {},
  "graphics": {
    "heartGraphicExample": {
      "type": "AVG",
      "version": "1.2",
      "width": 100,
      "height": 100,
      "items": [
        {
          "type": "path",
          "pathData": "M 10,30 A 20,20 0,0,1 50,30 A 20,20 0,0,1 90,30 Q 90,60 50,90 Q 10,60 10,30 z",
          "fill": "pink"
        }
      ]
    }
  }
}

To import an SVG file and create a new document

1. In the developer console, open the skill for which you want to create this document.
2. In the left-hand navigation, click Multimodal Responses.
3. Click Create with Authoring Tool.

4. Click Upload

   

5. Either drag your SVG file to the Upload your Visual Response dialog box, or click Browse and locate the file to import.
6. Click Upload.
7. When prompted, click Convert.
   • If the conversion completes without errors, the tool opens to a new APL document that displays the converted graphic. The new document has an object in the graphics property and a VectorGraphic that references the graphic in the mainTemplate. The name for the graphic defaults to the file name for the file you imported.
   • If the conversion encountered any errors, the tool displays a list of the unsupported features. Review the list and click Continue. To prevent these errors, make sure your graphic doesn't use any features that aren't supported in the authoring tool. For the list of supported features, see Supported features.

Edit an AVG in the authoring tool

You can edit an AVG in the authoring tool.

1. In the authoring tool, open the APL document that contains the graphic you want to edit.
2. In the toolbar, click the GRAPHICS toolbar.

3. Select the GUI View tab. The tool displays all the AVGs in the document.

   

4. For the graphic to edit, click the properties under the graphic name, and then edit the properties in the middle pane.

Supported features

The authoring tool supports converting SVG version 1.1. For details about SVG format, see the MDN documentation.

The converter doesn't support all features of SVG. The following table summarizes the SVG features that the authoring tool converts to AVG.

Troubleshooting

Issue: Conversion complete with issues message

Symptoms

The authoring tool displays a message stating "Conversion Complete with Issues." The message lists unsupported SVG features.

Try this

This issue means that the authoring tool could import the file, but the results might not be what you expect due to the unsupported features.

Note the list of unsupported features shown in the message. Click Continue to see the resulting graphic without the unsupported features.

For the list of supported features, see Supported features.

Issue: There were errors converting your SVG file

Symptoms

The authoring tool displays a message stating "There were errors converting your SVG file." The message lists unsupported SVG features.

Try this

This error means that the authoring tool couldn't import the file at all due to unsupported features.

Note the list of unsupported features shown in the message. Click Cancel to exit the conversion, or Start Over to import a different file.

Issue: File type not supported error

Symptoms

The authoring tool displays a message stating "File type not supported. Please select an APL, valid Lottie .json, or graphic .svg file."

Try this

This error means that the authoring doesn't recognize the file as a valid SVG file. Click Cancel or Start Over and select a valid SVG file.

Issue: Preview pane displays blank screen after a successful conversion

Symptoms

The authoring tool displays a message indicating that the conversion was successful. However, the preview pane in the authoring tool displays a blank, black viewport with no graphic. The left-hand pane of the tools displays the expected AVG and VectorGraphic code.

Try this

This situation might occur if the graphic you imported contains text and images that use black as the color. The graphic imported correctly, but is not visible against the default black viewport background.

Either change the background color for the document, or change to the light theme to see the black graphic.

The following examples show how you can change the background color or theme. Details are removed from the imported AVG (myGraphic) for brevity.

Change the viewport theme

Add the document-level theme property to the top level of the document and set it to light.

{
  "type": "APL",
  "theme": "light",
  "version": "2024.3",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": {
      "type": "VectorGraphic",
      "source": "myGraphic"
    }
  },
  "graphics": {
    "myGraphic": {}
  }
}

Change the document background to a different color

Add the document-level background property and set it to a color or gradient.

{
  "type": "APL",
  "version": "2024.3",
  "background": "yellow",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": {
      "type": "VectorGraphic",
      "source": "myGraphic"
    }
  },
  "graphics": {
    "myGraphic": {}
  }
}

Use the AlexaBackground responsive component

The AlexaBackground component in the alexa-layouts package gives you more control over the background. You can use a color, gradient, image, video, or default Alexa background. Because mainTemplate displays a single component, you must add a Container and move the AlexaBackground and VectorGraphic components into the items array for the Container.

To access the AlexaBackground component, add the current version of alexa-layouts to the import array.

The following example shows how to import the alexa-layouts package, and then how to arrange AlexaBackground and VectorGraphic in a Container. This example uses the default Alexa background.

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": {
      "type": "Container",
      "width": "100%",
      "height": "100%",
      "items": [
        {
          "type": "AlexaBackground"
        },
        {
          "type": "VectorGraphic",
          "source": "myGraphic"
        }
      ]
    }
  },
  "graphics": {
    "myGraphic": {}
  }
}

For more about using backgrounds in APL, see Combine Content with Backgrounds, Borders, and Headers.

Related topics

• Build Documents in the Developer Console
• Create and Edit an APL Document
• Preview an APL Document
• Alexa Vector Graphics Format
• VectorGraphic

Last updated: Nov 28, 2023