Tour Integration for CRM Systems or Portals


This page is suppose to show a more comprehensive view on possible tour integration scenarios where tours can be integrated accross different expose pages for multiple customers.
Before showing possible approaches on how to link web site pages to virtual tours in the immoviewer system we will show more details about the immoviewer API call all of this approaches are based on:

Full URL request information

URLhttps://app.immoviewer.com/rest/v1/tour

Method: GET

Request Query parameters:

Parameter
Meaning
internalIDitem's internalID (unique and provided by immoviewer)
identityImmoviewer user identity 
externalIDitem's external ID (usually the ID of the CRM software)
namename of the virtualTour
objectIDitem's internal ID (the internal ID of the portal: Immobilienscout24, Immonet, Immowelt...)
portalTypePortal type. This is required when the objectID is specified.
scopeSpecify what do you want to be returned in the response as comma separated list of a subsection of following values: pdf,qrCode,firstImage,title,iframe, default: firstImage,title,iframe


Return Type:

Parameter
Meaning
pdf
Direct link to the pdf generated for the tour
qrCodeDirect link to the qrCode generated for the tour (256x256).
firstImageURL of the default image
nameTitle of the tour
iframeA blank website which only contains a tour player (useful for iframe integration in your own website)

Please refer to the next sections for more details about valid usage of the endpoint.

General Data Handling

If correctly implemented the request will always return one of the two following datastructures

Tour Available Example Response:

{"iframe":"https://app.immoviewer.com/portal/tour/1123190","firstImage":"https://img.immoviewer.com/items/mothership/593694204cedfd005096a2ca/Tour/1080-images/Nonnenmacher3608249.jpg?v=1495797951677","name":"Drohnen- u. Erfassungsservice - Komplettpaket"}

Tour Not Available (e.g. deactivated, invalid parameters):

{"type":"ITEM_NOT_FOUND"}

Integration Approaches

Warning

To avoid getting blocked by the immoviewer API we recommend using some caching for the results of the shown request instead of doing a request on every page load especially if you know that your page is generating a lot of traffic. 
Please contact us under support@immoviewer.com if you have questions about whether your expected traffic amount will exceed the accepted amount.

via ExternalID

For showing a virtual tour in the expose webpage of a CRM System Provider or Portal requesting the tour data with the externalID appears to be the most appropriate approach. Since the externalID is defined by the user or CRM Software itself its most likely "known" in the context of the website already. To apply this approach three things have to be provided in order to embed a virtual tour into the website:

  1. The Website needs to store a so called immoviewer user identity which allows the immoviewer system to identitfy the user for which a tour is requested in the request
  2. The User needs to store the externalID for the tour in the immoviewer System under app.immoviewer.com/portal/
  3. The Website needs to call the shown request with the parameters externalID and identity

The obvious advantage of this approach is that the website is always showing the content of immoviewer without the customer having to put some configuration on a per object level. However your system needs to be able to store the identity for the immoviewer service for each user.

via InternalID

If you prefer your user to always manually put the immoviewer tour ID on each object you might use this unique ID for each tour to request it directly. To apply this approach two things have to be provided in order to embed a virtual tour into the website:

  1. The Website needs to allow the user to put an ID for each object
  2. The Website needs to call the shown request with the this id as "internalID"

Visual Appearance of tour integration on website

With the data given from the described API endpoint you have everything you need to design your own embedded tours. You may decide to directly embed the tour into the webpage or only show it after clicking an a preview image.

In case you do not want to implement the logic for showing the tour on the page yourself you may adapt your examples shown in Tour Integration examples for Websites.