Assembly configuration strings

Assembly configuration strings let you express complex, multi-product builds in a single, URL-friendly notation. A configuration string can:

Group multiple “parts” (each part separated by ~)
Define one or more products within each part (comma-separated)
Attach component selections (in parentheses)
Flag exact selections (!)
Specify placement (Placement@Component)
Embed personalization text (Placement:URL-encoded-text)

Configuration strings structure

An assembly configuration string is made up of one or more parts, joined by tildes (~). Each part tells the system which products go together and, if you like, exactly which components (or text) go with each product.

Parts (~-separated)

For example,

CODE

A,B~P1,X,Y~P2,U

Part 1 products: A,B
Part 2 products: P1,X,Y
Part 3 products: P2,U

Products (comma-separated inside a part)

List each product ID you want in that part, separated by commas.

Simple case: A,B means “load product A and product B together” with no extra selections.

Adding component selections

If you want to select some initial components for a product, put those in parentheses right after the product ID:

CODE

A(C1,C2)

By default, component selections will be fuzzy matched to available components. For example, if you enter an initial selection Script it would match a component named FontScript.

Components are matched by either component code or component SKU.

Exact match

Prefix a component with ! to force that exact selection.

For example:

CODE

A(!C1)

Placements

Unless specified, the initial selection will try to apply to all placements; that is, every placement would be checked to see if the selected component exists. If it is necessary to restrict the selection to a specific placement, use the @ specifier:

CODE

A(Placement@Component)

@ selector can be combined with ! exact specifier. For example:

CODE

B(Side@!C5)

Means “product B, component C5 at Side, and it must match exactly C5.”

Attribute values

In order to set placement-specific attributes and values, append the placement selector with @ symbol followed by a key;value couplet:

CODE

ProductID(Left@Color;Red)

Note that this selector uses the same style selection modifier as the component selection. Equal sign characters are not allowed in component IDs.

Both the attribute key and value should be encoded using the same encoding scheme as the personalization text.

Personalization text

If a placement supports personalization (e.g. a name or message), free-form text can be included by using Placement:EncodedText shortcut. This shortcut is equivalent to Placement@personalization-text=Text selector.

For example:

CODE

A(Name:%2BJohn%20Doe)

Personalization text shall encoded as a URI component. In JavaScript, this can be achieved using encodeURIComponent function. Additionally, ( and ) should also be percent-encoded.

( → %28
) → %29

Images

For placements of dynamic-image type, a selected image name can be provided using $ shortcut: Placement$image. If the image code does not start with a https:// prefix, the image is presumed to be hosted by the target account asset library.