It's easy to add rich interactivity to the objects in your 3D scenes using the web editor UI. But the awe.js API also gives you the power to add interactivity through custom Javascript. This guide gives you a simple example of how to get started.

To follow this example first add an object to an image based WebAR scene. Now your users can scan your target image with their device and see your digital content projected over the top of it. And they can see your content from all sorts of angles by moving their device around relative to the target image.

But sometimes you want to make it easy for them to see all angles of your content. In this case it can be useful to let them rotate a 3D model by sliding their finger (or dragging their mouse) from side-to-side. Of course you can also detect swiping up-and-down, but in this simple example we'll just focus on side-to-side. In this case we'll then rotate the object around it's vertical or Y axis, however you could use this input to create any sort of animation or effect you want.

Within the object editor for your image based view, select the object you want the user to be able to manipulate. Then in the bottom right hand corner you'll see a ... button. Select this and choose Actions from the menu. Then select the On load event and select Custom script. This will let you setup some custom Javascript that will be run as soon as this object is loaded and presented to the user for the first time. You can see more information about all of the different Action options in our support area.

Now paste the code below into the text area and select Done to save this. The code below is well commented and should give you a good example of how easy it is to add interactivity using the awe.js API.

// setup vars for this projection once it has loaded
var projection = awe.projections.view(projection_id); // projection_id is automatically pre-populated in Action Custom Scripts
var projection_rotation_y = projection.rotation.y; // capture this objects initial y rotation
var projection_visible = true; // this object has just be shown so we know it is now visible

// setup code to handle user gestures using a touch_gesture listener (note there is also a touch_gesture_end event)
window.addEventListener('touch_gesture', handle_gesture);
function handle_gesture(e) {
  if (projection_visible) { // only handle gestures if the projection is visible
    if (e.detail.swipe_x) { // handle side-to-side swipes
      projection_rotation_y = (projection_rotation_y-e.detail.swipe_x)%360; // update the y rotation value based on the user's swipe
      projection.update({ rotation:{ y:projection_rotation_y } }); // rotate the object around it's y axis
    }
  }
}

// track this projection's visibility using a tracking_state_changed listener
window.addEventListener('tracking_state_changed', handle_tracking_state_changed);
function handle_tracking_state_changed(e) {
  projection_visible = e.detail;
}

// remove these listeners when this view is unloaded
(async function() {
  await awe.on_state('view_unloaded', true);
  window.removeEventListener('touch_gesture', handle_gesture);
  window.removeEventListener('tracking_state_changed', handle_tracking_state_changed);
})();

Now you can load this view again, and once your digital content is shown over your target image try swiping your finger (or dragging your mouse) from side-to-side. When you do this you'll see that the object you added your custom script to will spin based on your gesture movement.

Easy isn't it!

The tricky part is working out how you want this to fit into your overall interaction design for the experience you are creating and how you let your users know to interact like this. You may like to also checkout our guide to Adding HTML content to your awe app to add an overlay message or similar. The design options are endless, and because it's all based on Javascript, HTML and CSS you can do almost anything you want.

The example above shows you how to add this type of interactivity to an object that's projected onto a target image. Adding this to a 360° or VR scene can be a little more tricky because by default the swipe (or click and drag) side-to-side movement lets the user pan the world (e.g. rotate the scene around it's Y axis). Let's look at how we can add this using 2 separate Actions.

First setup a standard view and add your object to the scene. Now you're ready to start adding the Actions.

Within the object editor for your standard view, select the object you want the user to be able to manipulate. Then in the bottom right hand corner you'll see a ... button. Select this and choose Actions from the menu. Then select the On load event and select Custom script. Paste the code below into the text area and select Done to save this.

// setup code to handle user gestures using a touch_gesture listener
window.addEventListener('touch_gesture', handle_gesture);
function handle_gesture(e) {
  if (window.projection) { // only handle this gesture if the window.projection variable is populated
    if (e.detail.swipe_x) { // handle side-to-side swipes
      projection_rotation_y = (projection_rotation_y-e.detail.swipe_x)%360; // update the y rotation value based on the user's swipe
      projection.update({ rotation:{ y:projection_rotation_y } }); // rotate the object around it's y axis
    }
  }
}

Now select the Add event option and select On select event and select Custom script. Paste the code below into the text area and select Done to save this.

awe.settings.update({ data: { value: true }, where: { id: 'prevent_pan_and_zoom' }}); // turn off swipe to pan
window.projection = awe.projections.view(projection_id); // set this projection in the global window.projection variable
window.projection_rotation_y = projection.rotation.y; // get the initial rotation of this projection

awe.util.add_one_event_listener('scene_clicked', undefined, function() { // setup a one-time listener for when the user taps/clicks the scene background
  awe.settings.update({ data: { value: false }, where: { id: 'prevent_pan_and_zoom' }}); // turn back on swipe to pan
  window.projection = undefined; // set the global window.projection variable to undefined
  window.projection_rotation_y = undefined; // set the global window.projection_rotation_y variable to undefined
});

Now you can load this view again, and once your digital content is shown try tapping or clicking on your object then try swiping your finger (or dragging your mouse) from side-to-side. When you do this you'll see that the object you added your custom script to will spin based on your gesture movement. Then try tapping or clicking the scene background, then try swiping your finger (or dragging your mouse) from side-to-side. Now when you do this you'll see the scene rotates from side to side. This means you can change modes by either selecting the object or selecting the scene background.

This should give you a good idea of how easy it is to add interactivity using custom Javascript and the awe.js API.