Search
Loading...
Skip to content

Store Custom Metadata

CE.SDK allows you to store custom metadata in your scenes. You can attach metadata to your scene or directly to your individual design blocks within the scene. This metadata is persistent across saving and loading of scenes. It simply consists of key value pairs of strings. Using any string-based serialization format such as JSON will allow you to store even complex objects. Please note that when duplicating blocks their metadata will also be duplicated.

Working with Metadata#

We can add metadata to any design block using fun setMetadata(block: DesignBlock, key: String, value: String). This also includes the scene block.

engine.block.setMetadata(scene, key = "author", value = "img.ly")
engine.block.setMetadata(block, key = "customer_id", value = "1234567890")
engine.block.setMetadata(block, key = "customer_name", value = "Name")

We can retrieve metadata from any design block or scene using fun getMetadata(block: DesignBlock, key: String): String. Before accessing the metadata you check for its existence using fun hasMetadata(block: DesignBlock, key: String): Boolean.

    // This will return "img.ly"
    engine.block.getMetadata(scene, key = "author")


    // This will return "1000000"
    engine.block.getMetadata(block, key = "customer_id")

We can query all metadata keys from any design block or scene using fun findAllMetadata(block: DesignBlock): List<String>. For blocks without any metadata, this will return an empty list.

// This will return ["customer_id", "customer_name"]
engine.block.findAllMetadata(block)

If you want to get rid of any metadata, you can use fun removeMetadata(block: DesignBlock, key: String).

    engine.block.removeMetadata(block, key = "customer_id")


    // This will return false
    engine.block.hasMetadata(block, key = "customer_id")

Metadata will automatically be saved and loaded as part the scene. So you don’t have to worry about it getting lost or having to save it separately.

    // We save our scene and reload it from scratch
    val sceneString = engine.scene.saveToString(scene)
    scene = engine.scene.load(scene = sceneString)


    // This still returns "img.ly"
    engine.block.getMetadata(scene, key = "author")


    // And this still returns "Name"
    engine.block.getMetadata(block, key = "customer_name")

Full Code#

Here’s the full code:

import android.net.Uri
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import ly.img.engine.DesignBlockType
import ly.img.engine.Engine


fun storeMetadata(
    license: String,
    userId: String,
) = CoroutineScope(Dispatchers.Main).launch {
    val engine = Engine.getInstance(id = "ly.img.engine.example")
    engine.start(license = license, userId = userId)
    engine.bindOffscreen(width = 100, height = 100)


    var scene = engine.scene.createFromImage(
        Uri.parse("https://img.ly/static/ubq_samples/imgly_logo.jpg"),
    )
    val block = engine.block.findByType(DesignBlockType.Graphic).first()


    engine.block.setMetadata(scene, key = "author", value = "img.ly")
    engine.block.setMetadata(block, key = "customer_id", value = "1234567890")
    engine.block.setMetadata(block, key = "customer_name", value = "Name")


    // This will return "img.ly"
    engine.block.getMetadata(scene, key = "author")


    // This will return "1000000"
    engine.block.getMetadata(block, key = "customer_id")


    // This will return ["customer_id", "customer_name"]
    engine.block.findAllMetadata(block)


    engine.block.removeMetadata(block, key = "customer_id")


    // This will return false
    engine.block.hasMetadata(block, key = "customer_id")


    // We save our scene and reload it from scratch
    val sceneString = engine.scene.saveToString(scene)
    scene = engine.scene.load(scene = sceneString)


    // This still returns "img.ly"
    engine.block.getMetadata(scene, key = "author")


    // And this still returns "Name"
    engine.block.getMetadata(block, key = "customer_name")


    engine.stop()
}