The ReplaceableJson Guide

Update time : 2020-10-19 18:17:49

ReplaceableJson is a kind of asset editing feature that allows developers to edit or replace assets in an advanced method. By means of ReplaceableJson, you can replace or edit the advanced texts or images in templates. With better expandability compared to previous version, ReplaceableJson is a great function for you to add more features to your editable assets.

Data Structure

Most attributes are optional, and you can set corresponding attributes based on your needs. And most attributes are required, which means you should keep your eyes on the attribute type and do not set the wrong type. The data structures in the old version are compatible in the new ReplaceableJson. ReplaceableJson is a json array for replacing assets.

[
    {..}, //  The followings are examples of data structure of replaceble assets.  
    {..}
]

• Dynamic Template

  The common structure for replacing assets in dynamic template is as follows.

{
    \"main_file\" : \"/path/to/asset_file.log\", // Main image asset replacement 
    \"replaces\": [  // Replace advanced one or multiple additional assets related to main replacement image. 
        {  // Replace advanced image
            \"d_key_prefix\": \"dtext\",    // Set \"dtext\" as the prefix for an image. Find and replace the image by the prefix \"dtext\". (Note that the field is d_key_prefix.) 
            \"type\": 1, // Types: 1-image, 2-text, 3- rich text. 
            \"file\": \"/home/slayer/Desktop/workspace/assets/235_41_text1.png\" // The path of new asset. 
        },
        { // Replace advanced text
            \"d_key_prefix\": \"dtext\", // Set \"dtext\" as the prefix for text. Find and replace the text by the prefix \"dtext\". (Note that the field is d_key_prefix.) 
            \"type\": 2,
            \"attr\":{
                \"text\":  Center new text content. 
            }
        }
    ]
}

The common structure used for accurately replacing addtional assets that are not belong to the main file.

The object structures in the replaces above apply to replace the advanced texts or images in dynamic template. Replacement methods: d_key_prefix is used for finding and replacing specific asset by the prefix you set. d_key is used for finding and replacing specific asset accurately by the UI Key.

Steps of Using d_key And d_key_prefix

Both d_key and d_key_prefix are related to the ui_key of the template, and you may need to follow the steps below when using.

• Step 1: What kind of feaures can be achieved by ui_key? You can refer to The Features of UI Key.

• Step 2: Designer marks and exports dynamic template by the following video guide. The Advanced Video Replacement Guide in Dynamic Template

• Step 3: Designer needs to agree with developer what the ui_key or ui_key prefix is that needs to be replaced.

• Step 4: Developer assembles the data and invokes the interface of setReplaceableJson according to the ReplaceableJson Guide.

Tip:

The functions of setReplaceableFiles, setDynamicSubFiles and setDynamicSubTexts in old version have been implemented already in the new setReplaceableJson, hence you are not allowed to call the old and new versions simultaneously.

An Example of Optimizing Data Structure

// Dynamic template, please mark ui_key on the layer. 
[
    {
        \"main_file\" : \"/path/to/asset_file.jpg\", // Main replacement assets
        \"attr\":{
            \"loop\": 1, // Video or GIF assets are valid. 0- let SDK decide the loop type, 1- loop, 2- not loop (new in version 2.0), and the default volume value is 0.
            \"volume\": 0.5,  // Video assets are valid, and volumes should be greater than or equal to 0. Standard volume range is 0 to 1, but it can be greater than 1 (new in version 2.0), and the default volume value is 0. 
        },
        \"replaces\": [  // Advanced replacement assets related to main replacement assets.
            {  // Imgae replacement
                \"d_key_prefix\": \"dtext\",    // Set \"dtext\" as the prefix for an image. Find and replace the image by the prefix \"dtext\". (Note that the field is d_key_prefix.)
                \"type\": 1, // Types: 1- image or video, 2- text, 3- advanced character.
                \"file\": \"/home/slayer/Desktop/workspace/assets/235_41_text1.png\", // The path of image replacement
                \"attr\":{
                    \"loop\": 1, // Video or GIF assets are valid, 0- let SDK decide the loop type, 1- loop, 2- not loop (new in version 2.0), and the default volume value is 0. 
                    \"volume\": 0.5,  // Video assets are valid, and volumes should be greater than or equal to 0.  Standard volume range is 0 to 1, but it can be greater than 1 (new in version 2.0), and the default volume value is 0. 
                    \"adapt_type\":0,  // Adaptation types: 0- use the real size of image, 1- cover( center and scale image to fill up space),  2- contain ( center and scale to display full image), 3- fill (scale image to fill space), 4- transform ( use the matrix corresponding to the transform field). 
                    // New in version 2.2.0.
                    \"transform\":[a,c,e,b,d,f] // Standard Affine matrix defaults to unit matrix.
                    \"clip_start\":0.0，// The start time of video cropping. You do not need to pass the parameter if you do not want to crop video size. Note that the clip_end must be greater than clip_start (the beginning of sart point). 
                    \"clip_end\":-1.0, // The end time of video cropping. If the video duration is greater than 0 second, then you need to crop the video size, otherwise you do not need. 

                }
            },
            { // Text replacement
                \"d_key_prefix\": \"dtext\", // Set \"dtext\" as the prefix of the text. Find and replace the text by the prefix \"dtext\". (Note that the field is d_key_prefix.)
                \"type\": 2,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.
                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
                    \"stroke_width\":0.0, // The width of text stroke. 
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not.
                    \"size\":0, // Text size, unit in pixels. 
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles, which is valid during rendering. This method is under our recommendation.  / Choose one out of two.
                    \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages. It is valid when rendering.  / Choose one out of two.    
                }
            },
            { // Advanced text replacement
                \"d_key_prefix\": \"dtext\", // Set the \"dtext\" as the prefix of the text. Find and replace the text by the prefix \"dtext\". (Note that the field is d_key_prefix.)
                \"type\": 3,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.  
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.

                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
                    \"stroke_width\":0.0, // The width of text stroke.
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not.
                    \"size\":0, // Text size, unit in pixels. 
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles, which is valid during rendering. This method is under our recommendation.  / Choose one out of two. 
                    \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages./ Choose one out of two.
                }
            }
        ]
    },
    {  // If there is no main file, it means the asset will be found accurately by the UI Key you set in the d_key under replaces.
        \"replaces\": [
            { // Image replacement  
                \"d_key\": \"headimg\", // Set \"headimg\" as the UI Key for an image. Find and replace the image by the \"headimg\" accurately. (Note that the field is d_key.)
                \"type\": 1,
                \"file\": \"/home/slayer/Desktop/workspace/assets/235_41_text7.png\", //  The path of image replacement.
                \"attr\":{
                    \"loop\": 1, // Video or GIF assets are valid. 0- let SDK decide the loop type, 1- loop, 2- not loop (new in version 2.0), and the default volume value is 0. 
                    \"volume\": 0.5,  // Video assets are valid, and volumes should be greater than or equal to 0. Standard volume range is 0 to 1, but it can be greater than 1 (new in version 2.0), and the default volume value is 0. 
                    \"adapt_type\":0,  // Adaptation types: 0- use the real size of image, 1- cover( center and scale image to fill up space),  2- contain ( center and scale to display full image), 3- fill (scale image to fill space), 4- transform ( use the matrix corresponding to the transform field).
                    // New in version 2.2.0. 
                    \"transform\":[a,c,e,b,d,f] // Standard Affine matrix defaults to unit matrix.
                    \"clip_start\":0.0，// The start time of video cropping. You do not need to pass the parameter if you do not want to crop video size. Note that the clip_end must be greater than clip_start (the beginning of sart point). 

                    \"clip_end\":-1.0, // The end time of video cropping. If the video duration is greater than 0 second, then you need to crop the video size, otherwise you do not need.
                }
            },
            { // Text replacement
                \"d_key\": \"title\", // Set \'\'title\'\' as the UI Key for text. Find and replace text by the \'\'titile\'\'. (Note that the field is d_key.)
                \"type\": 2,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically. 
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.
                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB. 
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB. 
                    \"stroke_width\":0.0, // The width of text stroke. 
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not.
                    \"size\":0, // Text size, unit in pixels. 
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles, which is valid during rendering. This method is under our recommendation.  / Choose one out of two. 
                    \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages. It is valid when rendering. / Choose one out of two. 
                }
            },
            { //  Advanced text replacement. 
                \"d_key\": \"topic\", // Set \"topic\" as the UI Key for text. Find and replace text by the \"title\" accurately. (Note that the field is d_key.)
                \"type\": 3,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically. 
                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
                    \"stroke_width\":0.0, // The width of text stroke.
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not. 
                    \"size\":0, // Text size, unit in pixels. 
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles. This method is under our recommendation.  / Choose one out of two. 
                    \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages./ Choose one out of two. 
                }
            }
#       ]
     }
]

• Standard Template

  The replacement method by the editable assets order in config.json file in standard template.

// Each object in the array represents an editable asset. But if there is a null in the array, the asset it represents will not be replaced.
 [
     {
        \"type\":1, // Default value is 1. 
        \"main_file\": \"/home/slayer/Desktop/workspace/assets/1.jpeg\",
        \"attr\":{
            \"loop\": 1, // Video or GIF assets are valid. 0- let SDK decide the loop type, 1- loop, 2- not loop (new in version 2.0), and the default volume value is 0. 
            \"volume\": 0.5,  // Video assets are valid, and volumes should be greater than or equal to 0. Standard volume range is 0 to 1, but it can be greater than 1 (new in version 2.0), and the default volume value is 0.
            \"adapt_type\":0,  // Adaptation types: 0- use the real size of image, 1- cover( center and scale image to fill up space),  2- contain ( center and scale to display full image), 3- fill (scale image to fill space), 4- transform ( use the matrix corresponding to the transform field).
            // New in version 2.2.0.
            \"transform\":[a,c,e,b,d,f] // Standard Affine matrix defaults to unit matrix.
            \"clip_start\":0.0，// The start time of video cropping. You do not need to pass the parameter if you do not want to crop video size. Note that the clip_end must be greater than clip_start (the beginning of sart point). 
            \"clip_end\":-1.0, // The end time of video cropping. If the video duration is greater than 0 second, then you need to crop the video size, otherwise you do not need.
        }
     },{
        \"main_file\": \"\" // There is a null in the main_file, the editable asset it represents will not be replaced. 
     },{
        \"type\":2, 
        \"attr\":{
            \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.
            \"adapt\": true, //Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.    
            \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
            \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
            \"stroke_width\":0.0, // The width of text stroke.
            \"stroke_over_fill\":false, // Text stroke color over text fill color or not.
            \"size\":0, // Text size, unit in pixels. 
            \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles, which is valid during rendering. This method is under our recommendation.  / Choose one out of two.
            \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages./ Choose one out of two. 
        }
     },{
        \"type\":3, // The default value is 3, which is compatible with the Power Text in older versions. 
        \"attr\":{ // Advanced character animation 
            \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.   
            \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.
            \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
            \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
            \"stroke_width\":0.0, // The width of text stroke.
            \"stroke_over_fill\":false, // Text stroke color over text fill color or not.
            \"size\":0, // Text size, unit in pixels.
            \"font_family\":\"\", // Names of font family. It is recommended to find the loaded fonts in the SDK by font family names. / Choose one out of two
            \"font_file\":\"\"  // The path of text file. We recommend you use ttf font, and do not use the font set that contains multiple languages./ Choose one out of two.
        }
     },{
        \"main_file\": \"/home/slayer/Desktop/workspace/assets/3.jpeg\"
     }
 ]

Find and replace assets accurately by the prefix of ui_key in the standard template.

// The ui_key should be added to the assets that are to be edited, and the corresponding assets should be set to be editable. 
[
    {
        \"replaces\": [
            { // Image replacement
                \"d_key\": \"headimg\", // Set \"headimg\" as the ui_key for an image. Find and replace the image accurately by \'\'headimg\'\'.
                \"type\": 1,
                \"file\": \"/home/slayer/Desktop/workspace/assets/235_41_text7.png\", // The path of image
                \"attr\":{
                    \"loop\": 1, // Video or GIF assets are valid. 0- let SDK decide the loop type, 1- loop, 2- not loop (new in version 2.0), and the default volume value is 0. 
                    \"volume\": 0.5,  // Video assets are valid, and volumes should be greater than or equal to 0. Standard volume range is 0 to 1, but it can be greater than 1 (new in version 2.0), and the default volume value is 0. 
                    \"adapt_type\":0,  // Adaptation types: 0- use the real size of image, 1- cover( center and scale image to fill up space),  2- contain ( center and scale to display full image), 3- fill (scale image to fill space), 4- transform ( use the matrix corresponding to the transform field).
                    // New in version 2.2.0.
                    \"transform\":[a,c,e,b,d,f] // Standard Affine matrix defaults to unit matrix. 
                    \"clip_start\":0.0，// The start time of video cropping. You do not need to pass the parameter if you do not want to crop video size. Note that the clip_end must be greater than clip_start (the beginning of sart point). 
                    \"clip_end\":-1.0, // The end time of video cropping. If the video duration is greater than 0 second, then you need to crop the video size, otherwise you do not need. 
                }
            },
            { // Text replacement
                \"d_key\": \"title\", // Set \'\'title\'\' as the UI Key for text. Find and replace text by the \'\'titile\'\' accurately. (Note that the field is d_key.) 
                \"type\": 2,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.
                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
                    \"stroke_width\":0.0, // The width of text stroke.
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not. 
                    \"size\":0, // Text size, unit in pixels.  
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles, which is valid during rendering. This method is under our recommendation.  / Choose one out of two.
                    \"font_file\":\"\"  // The path of text file. We recommend you use ttf font and do not use the font set that contains multiple languages, which is valid during rendering./ Choose one out of two.
                }
            },
            { // Advanced text replacement.
                \"d_key\": \"topic\", // Set \"topic\" as the UI Key for text. Find and replace text by the \"title\" accurately. (Note that the field is d_key.)
                \"type\": 3,
                \"attr\":{
                    \"text\" : \"\", // Text content. If the number of character is longer than the default value designed in UI, it will be cut automatically.
                    \"adapt\": true, // Enable the text adaptation or not. When enabled, the text box and the font size will be adjusted automatically. When disabled, the characters that are longer than the default character number in the text box will be cut automatically.   
                    \"fill\" : \"#FFFFFF\", // Text fill color, formatted as RGB.
                    \"stroke\": \"#FFFFFF\", // Text stroke color, formatted as RGB.
                    \"stroke_width\":0.0, // The width of text stroke.
                    \"stroke_over_fill\":false, // Text stroke color over text fill color or not. 
                    \"size\":0, // Text size, unit in pixels. 
                    \"font_family\":\"\", // The names of font family. You need to call method to find the loaded fonts in SDK by the names of font family and then you can set the font styles. This method is under our recommendation.  / Choose one out of two. 
                    \"font_file\":\"\"  // The path of font file. It is recommended to use ttf fonts, but not a font set that contains multiple languages.  / Choose one out of two.

                }
            }
        ]
     }
]