Widget

Restrictions

The widget accepts an optional parameter data-request-restrictions to customize restrictions on attributes. If present, the parameter MUST be a JSON object with these parameters:

attr_name = {
  "restriction_type": {
    "field_ref":"value to restrict to"
  }
}

Multiple objects can be provided using attribute name as key (i.e. attr_name=username, email etc..). These objects must contain a restriction object. restriction_type: the restriction to apply. Only value is currently supported field_ref: the field to restrict. Only _self is presently supported.

Predicates

The widget accepts an optional parameter data-request-predicates to customize predicates on attributes. If present, the parameter MUST be a JSON object with these attributes:

{"predicate_name_1":"predicate_value_1", ...}

Multiple objects can be provided using predicate name as predicate_name and the desired value as predicate_value. Warning Only predicates already described in the proof template can be modified using these objects.

Contents

The widget accepts an optional parameter data-request-contents to customize the contents of attributes and proof template. If present, the parameter MUST be a JSON object with these attributes:

Listening callbacks

After the widget is integrated into a page, it will create an iframe that will load the Dizme Agent Widget page. The configuration of the widget will determine which content, such as a QR code, is displayed on the Dizme Agent Widget page.

The widget will generate callbacks to the main page based on user actions. This is the only reliable way to determine if the user has completed the flow or if they have encountered an error.

To enable the callbacks, the integrating page must declare a function with a single parameter and provide the function's name as the value for the "data-onauth" widget parameter.

As argument of function object will delivered like so: {"transaction_status": state, 'details': details}

where transaction_status is always present and will determine action.

Widget states
Widget States (in blue selected the happy path) with multi-read = false

Warning The state diagram above pertains specifically to flows where the "multi-read" feature is disabled. If this feature is enabled and a user reads the QR code multiple times, the flow will be halted at the "SHOW_QR" state and unable to proceed further. This is because the flow cannot determine the appropriate path to take after multiple reads of the QR code.

Customization

The Dizme Widget offers three different customization options, allowing for greater flexibility and personalization:

• Size: Customize the widget's size using the "data-size-widget" parameter.
• Language: Choose between Italian and English using the "data-lang" parameter. Additional languages can also be added if needed.
• View type: Use the "data-widget-type" parameter to customize the widget's view type. For example, it is possible to add a logo to the QR code or create a completely custom QR code.

When the widget type is set to "complete", the widget will handle all aspects of the user experience, including text in the selected language.

If the widget type is set to "qr-only", the widget will hide all text and only display the QR code and some animations. In this case, the handling of text and messages will be the responsibility of the integrating party, using transaction statuses provided by the "data-onauth" callback.

Finally, the widget type "invisible" will hide the QR code altogether by setting the iframe size to 0px*0px. In this case, the integrating party is responsible for rendering the QR code, which can be designed to their specifications. The QR code's contents will be provided in the "SHOW_QR" callback, inside the "link" field.

Examples

Simple example

<script async src="https://<<agent_url>>/widget-svc-static/widget_viewer/dizme_widget_v2.js"
    data-onauth="onDizmeAuth(res)"
    data-request-orgid="#ORGANIZATION NAME"
    data-request-service="#PUT HERE THE BUSINESS CODE OF SERVICE CONFIGURED"
    data-request-multi-read="false"
    data-request-template="#PUT HERE THE BUSINESS CODE OF PROOF CONFIGURED"
    data-request-id="#PUT HERE YOUR OWN REQUEST UID OR REMOVE TO AUTO GENERATE ONE"
    data-request-oob="true" #ENABLE OUT OF BAND"
    data-lang="en" # PUT en or it
    data-request-type="verify">
</script>
<script type="text/javascript">
    function onDizmeAuth(res) {
        console.log(res);
        if (res.proof_status === "SUCCESS") {
        } else if (res.proof_status === "FAILURE") {
        } else if (res.proof_status === "ABORTED") {
        }
    }
</script>

Full example with restrictions and contents update

<script
    src="https://agent-aws.dizme.io/widget-svc-static/widget_viewer/dizme_widget_v2.js"
    data-onauth="onDizmeAuth(res)"
    data-request-orgid="#ORGANIZATION NAME"
    data-request-service="#PUT HERE THE BUSINESS CODE OF SERVICE CONFIGURED"
    data-request-multi-read="false"
    data-request-template="#PUT HERE THE BUSINESS CODE OF PROOF CONFIGURED"
    data-request-id="#PUT HERE YOUR OWN REQUEST UID OR REMOVE TO AUTO GENERATE ONE"
    data-request-oob="true #ENABLE OUT OF BAND"
    data-lang="en # PUT en or it" 
    data-request-type="verify"
    data-request-restrictions='{
        "username": {
            "value": {
                "_self": "sersvsv"
            }
        },
        "email": {
            "value": {
                "_self": "some@example.com"
            }
        }
    }'
    data-request-contents='{
        "comment": [
            {
                "lang": "en",
                "message": "Proof description"
            },
            {
                "lang": "it",
                "message": "Descrizione della proof"
            }
        ],
        "q1": {
            "choice_list": [
                "YES",
                "NO"
            ],
            "description": [
                {
                    "lang": "en",
                    "message": "Important dynamic question"
                },
                {
                    "lang": "it",
                    "message": "Domanda dinamica importante"
                }
            ]
        }
    }'                   
    data-size-widget="normal"
    data-request-oob="true"
    data-widget-type="complete">
</script>

Resources

• widget_states.puml