You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f4898c2
Browse filesBrowse the repository at this point in the historyBrowse files
feat(viewer): rewrite getting started as an end-to-end path
The page stopped at the demo snippet. Readers who wanted to switch to
their own data had to reassemble the path themselves across the API and
Viewer sections.
The demo snippet now opens the page unchanged, so time to first render
stays at zero. Everything else is new:
- Add the "use your own models" path: application, cloud, project,
model, token.
- Move ProjectAccessToken into the viewer path. It was only documented
in /api/guides/authentication, which is not where someone integrating
the viewer looks. The current default path is pasting an ApiKey into
the page.
- Document the two main causes of a blank screen: ES modules blocked on
file://, and a container with no height.
- Add the ui config block for white labelling.
- Move the format list to "Going further".
- Link to existing reference pages instead of duplicating them.
Each model format is handled by its own native built-in viewer and interactions include **display**, **navigation**, **measurement** and **annotation**.
22
-
23
-
The BIMData Viewer is binded to the [BIMData API](/api/introduction/overview) and you can directly upload models using it or using the [BIMData platform](https://platform.bimdata.io/).
24
-
25
-
[The UI can be customized](./guide/index#graphical-user-interface) to organize the workspace as you need and a flexible javascript API using
26
-
[Vue 3](https://vuejs.org/) allows to create custom plugins to match your business perfectly.
27
-
However, you don't need to master Vue.js to develop a plugin and you can still update the DOM with jQuery if you like!
24
+
This guide takes you from an empty file to a model running in your browser. No
25
+
account needed for the first step. Count about 15 minutes for the whole page.
28
26
29
27
<ViewerMainPage />
30
28
31
-
## Installation
29
+
## See it running
32
30
33
-
You can directly download the BIMDataViewer from a **CDN** or you can install the [`@bimdata/viewer` package](https://www.npmjs.com/package/@bimdata/viewer) using **NPM**.
31
+
Create an `index.html` file, paste this, and open it. The identifiers below point
32
+
to our public demo model, so it works as-is.
34
33
35
34
::: code-group
36
35
@@ -100,3 +99,168 @@ You can directly download the BIMDataViewer from a **CDN** or you can install th
100
99
</html>
101
100
```
102
101
:::
102
+
103
+
That is the entire integration: an import, four identifiers, and a `mount()`.
104
+
105
+
::: warning Double-clicking the file will not work
106
+
ES modules are blocked on the `file://` protocol, so opening the file directly
107
+
gives you a blank page and a CORS error in the console. Serve it over HTTP
108
+
instead, with the *Live Server* extension in VS Code or `npx serve` in the folder.
109
+
:::
110
+
111
+
::: tip Blank page, no error?
112
+
The viewer fills its parent element. If the container has no height, nothing
113
+
renders. That is what the `height: 100vh` wrapper above is for.
114
+
:::
115
+
116
+
::: tip Pin the version in production
117
+
`@latest` is convenient while you experiment, but it means your page changes
118
+
whenever we ship a release. Pin an explicit version once you go live.
119
+
:::
120
+
121
+
## Use your own models
122
+
123
+
The demo identifiers are read-only and shared. To display your own data you need
124
+
your own `cloudId`, `projectId`, `modelIds` and `accessToken`.
125
+
126
+
### 1. Create an application
127
+
128
+
An **application** is your developer identity with BIMData, and it is what gives
129
+
you API credentials.
130
+
131
+
1. Go to [connect.bimdata.io](https://connect.bimdata.io) and sign in.
132
+
2. Open **Manage your application** → **Create an application**.
133
+
3. Set the access type to **`Confidential`**.
134
+
4.`base_url` and `redirect_uri` are required even though you will not use them
135
+
here. `http://localhost:8080/oidc-callback` will do.
136
+
137
+
You get a `client_id`, a `client_secret` and an `ApiKey`. See
138
+
[Create your application](/api/guides/application) for details.
139
+
140
+
::: danger Keep these on your server
141
+
These credentials grant full access to your data. They belong in your backend,
142
+
never in a web page. Step 3 covers what to put in the browser instead.
143
+
:::
144
+
145
+
### 2. Create a cloud, a project and a model
146
+
147
+
The fastest route is our demo endpoint, which creates a project with a model
148
+
already in it, with no upload and no processing wait.
149
+
150
+
```bash
151
+
# Create a cloud
152
+
curl --request POST 'https://api.bimdata.io/cloud' \
153
+
--header 'Content-Type: application/json' \
154
+
--header 'Authorization: ApiKey YOUR_API_KEY' \
155
+
--data '{"name": "My First Cloud"}'
156
+
157
+
# Create a demo project inside it
158
+
curl --request POST 'https://api.bimdata.io/cloud/CLOUD_ID/create-demo' \
159
+
--header 'Content-Type: application/json' \
160
+
--header 'Authorization: ApiKey YOUR_API_KEY'
161
+
162
+
# List its models
163
+
curl --request GET 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/ifc' \
164
+
--header 'Authorization: ApiKey YOUR_API_KEY'
165
+
```
166
+
167
+
Each response gives you the identifier for the next call.
168
+
169
+
You can also create a project and upload your own IFC from the
170
+
[BIMData Platform](https://platform.bimdata.io/), then read the identifiers from
171
+
the URL.
172
+
173
+
::: warning A project created by hand is not visible to your app
174
+
Your application does not automatically have access to your user's data, and the
175
+
reverse is also true. To connect the two, invite yourself into a cloud created by
176
+
your app. See
177
+
[Share data between App and Platform](/api/guides/share_data).
178
+
:::
179
+
180
+
### 3. Create a token for the browser
181
+
182
+
Whatever you write in the page is readable by your users. So the token you pass
183
+
to the viewer must not be your application's `ApiKey`, which can read *and
184
+
delete* everything you own.
185
+
186
+
Use a **ProjectAccessToken** instead: temporary, read-only, limited to one
187
+
project.
188
+
189
+
```bash
190
+
curl --request POST 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/access-token' \
191
+
--header 'Content-Type: application/json' \
192
+
--header 'Authorization: ApiKey YOUR_API_KEY' \
193
+
--data '{
194
+
"expires_at": "2026-12-31T23:59:00Z",
195
+
"scopes": ["model:read"]
196
+
}'
197
+
```
198
+
199
+
`model:read` opens models and is the minimum scope the viewer requires. See
200
+
[Scopes](/api/guides/scopes) for the full list, and
201
+
[Authentication](/api/guides/authentication) for other flows.
202
+
203
+
::: tip In production
204
+
Generate a fresh 12-hour token from your backend each time a user opens the
205
+
viewer. Your `ApiKey` stays on your server, and the browser only ever holds a
206
+
short-lived, narrowly scoped token.
207
+
:::
208
+
209
+
Drop your four values into the snippet above, and you are running on your own
210
+
data.
211
+
212
+
## Make it yours
213
+
214
+
The default interface carries BIMData branding. One configuration block removes
215
+
it and lets the viewer blend into your own product:
216
+
217
+
```js
218
+
constbimdataViewer=makeBIMDataViewer({
219
+
api: { /* ... */ },
220
+
locale:"fr",
221
+
ui: {
222
+
header:false,
223
+
bimdataLogo:false,
224
+
version:false,
225
+
style: { backgroundColor:"F5F5F5" },
226
+
},
227
+
});
228
+
```
229
+
230
+
Native plugins can be turned off entirely with `plugins: false`, or one by one:
231
+
232
+
```js
233
+
plugins: {
234
+
bcf:false,
235
+
measure3d:false,
236
+
section:false,
237
+
viewer3d: { navCube:false, help:false },
238
+
}
239
+
```
240
+
241
+
Full list of options:
242
+
[makeBIMDataViewer](/viewer/reference/makeBIMDataViewer) and
0 commit comments