Integration

Calling the services / integration of the iFrame with the service

After activation, your service will be integrated into enterprise via Iframe.

For the integration the Iframe URL for the service must be publicly accessible. You inform us about this URL for your service once, when we include you as a provider for the marketplace.

The URL that can be used for the iframe of the service is also signed. We use the same procedure as for the signature when activating a provider.

Your task as a provider is to independently check the URL against the signature.

The following information is transferred signed when the URL is called:

  • Client name: customerName
  • User Web ID: customerWebId
  • User ID: userId
  • API-Claim: apiClaim (used for user verification, see Observe user rights when reading via API. Must be returned as extendedclaim for reading calls)
  • If the user is in a group, group ID: groupId
  • Timestamp: timestamp (format: Unix timestamp in seconds, the past seconds since Thursday, January 1, 1970, 00:00 UTC)
  • Parameters defined by macros (e.g. ID of a property or address; language parameter language for multilingual properties)
  • Image ID: If images are selected on the Files tab in real estate, the image IDs are passed as parameter imageIds.

Update parent window and close Shop-Iframe:

It is possible to specify a type with the Javascript function processTypeToonOffice(type) to close the service frame or to trigger the update of the parent window in onOffice enterprise. For example, you could use it to update the parent window after you have transferred an image or data to enterprise so that the user can see the changes directly.

For this purpose the message.type is used, which can contain the following types:

  • onOffice.service.refreshParent (Parent window in enterprise is updated)
  • onOffice.service.refreshParentAndClose (parent window in enterprise is updated and the service popup is closed)
  • onOffice.service.closeProviderWindow (The service popup is closed)

This method is to be implemented by you. In addition to the “onOfficeType” parameter a timestamp and the signature of all values should be sent. As already with the pay popup.

The Javascript function can be seen here in the demo store and 3 buttons in the demo store trigger the actions here.

Advice Safari:

Because Apple’s Safari browser blocks third-party cookies and deletes first-party cookies relatively quickly, we recommend that you unlock and set up your service to work without cookies.

Example view of an unlocked service:

In this popup you present your products and prices via iframe. The user can order your products directly. In the next step the popup opens for payment confirmation and processing.

Missing context

Some services, such as a floor plan optimization, require a property or address reference. The user must be in the data record of a property or address when this service is called. The required context information, such as the real estate ID (estateid) or the address ID, is transferred to you.

For multilingual real estate, the language parameter language is transferred in addition to the parameter estateid. You have to specify this language as estatelanguage when reading and writing real estate using the API.

If the user is at a point in the software where this reference cannot be made, a message appears:

“This service can only be accessed from a property/address.”

Live and beta customers

onOffice Enterprise users can be either live or beta customers, then the URLs are “smart.onoffice.de” or “beta.smart.onoffice.de“. In the live system, the source code is updated monthly every first Tuesday of the month. In the beta system, the source code is updated twice a week, on Tuesday and Thursday.

Your provider client is a beta client. Most customers use live clients. This means that requests can come from the two URLs “smart.onoffice.de” or “beta.smart.onoffice.de”.

If you have used the source code of our demo shops as a template, you do not need to set anything on your page.

However, if you need the information whether a customer is a live or a beta customer, this can be read out via macro. If you want to have the macro integrated into your service URL or activation URL, please let us know at marketplace-dev@onoffice.de.

This post is also available in: German