(c) Copyright 2019-2023, Cappasity Inc. All rights reserved.
Cappasity is a SaaS solution that allows e-commerce businesses to create and display interactive 3D images on websites, mobile, and VR/AR apps to increase conversion and reduce product returns.
An online retailer creates 3D images of products using the Easy 3D ScanTM software and uploads them to the Cappasity platform account. Once integrated into the e-commerce website, the Cappasity PHP SDK synchronizes the retailer's catalog with the account based on matching SKU numbers. It enables the display of the required iFrame on the product page without its manual embedding for each product in the catalog.
- Store-side product catalogue
- ID - unique product identifier
- SKU - identification code that is applied to products. SKU code often reveals product details such as color, size, manufacturer and brand.
- Cappasity Account with 3D Views
- ID (example:
38020fdf-5e11-411c-9116-1610339d59cf
) - unique identifier of the Cappasity 3D View. We use it internally to identify the 3D View. You need it to synchronize product catalogue on your online store with the one on our platform and render Cappasity Player via iFrame. - SKU - unique identifier assigned to your Cappasity 3D View. In order to be synchronized with your store-side product, it should match corresponding SKU of the product on your website.
- ID (example:
Each product you want to integrate has its inner ID on your store side and one or more corresponding SKU codes. Sometimes a product could also have variants with their own IDs and SKU numbers.
Visit our website cappasity.com to download the Easy 3D Scan software, read instructions and create a 3D View yourself or to find Cappasity certified photo partner who will do this for you.
Sign up at 3d.cappasity.com to create and upload 3D Views. Fill in corresponding SKU identifier for those 3D Views that you want to synchronize. Each resulting model has its inner Cappasity View ID. You need this IDs to generate an iFrame code for the player.
Generate an API token on security settings page at your Cappasity account.
You can generate the embed code by Cappasity View ID. In order to get Cappasity View IDs you need to match your products SKUs with 3D Views. You can do it with our SDK.
In general, to get the matches you should register a synchronization job via our SDK to have 3D images embedded into your website. As your product database could be huge, it could take some time to process it. Our server processes your request and stores the result. You should specify how you want to get the processing result: via push or pull. In the push case, you should also specify the callback URL on job registration. Once processing is done, our server sends the result to the specified callback URL. In the pull case, you should keep track of the job state and the results by yourself. When you get the result, you should store received matches for further usage.
Let's say you have:
- Products on your store side:
- Product with ID
111
without options with single SKUSKU-111
- Product with ID
222
with options that have IDs222a
and222b
, product option222a
has SKUSKU-222-a
and product option222b
has SKUSKU-222-b
- Product with ID
333
with single SKUSKU-333
- Product with ID
- 3D Views uploaded on Cappasity side:
- View with ID
00000000-0000-0000-0000-000000000111
and SKUSKU-111
- View with ID
00000000-0000-0000-0000-00000000222a
and SKUSKU-222-a
- View with ID
00000000-0000-0000-0000-00000000222b
and SKUSKU-222-b
- No corresponding view for product with SKU
SKU-333
- View with ID
Then collected items are:
$collectedItems = [
[
'id' => '111',
'aliases' => ['SKU-111'],
],
[
'id' => '222',
'aliases' => ['SKU-222-a'],
],
[
'id' => '222',
'aliases' => ['SKU-222-b'],
],
[
'id' => '333',
'aliases' => ['SKU-333'],
],
]
Notice that options IDs are not present. So you should be sure you can find back the product option ID by its SKU to handle the matches later.
Also consider the synchronization limits.
Collect data as described above and register a synchronization job.
use CappasitySDK\Client\Model\Request;
$registerSyncJobId = $client
->registerSyncJob(Request\Process\JobsRegisterSyncPost::fromData(
$collectedItems,
'push.http',
'http://your-callback-url.com/foo/bar
))
->getBodyData()
->getId(); // a9673347-8f2e-4caa-83e9-4139d7473c2f:A1
Your /foo/bar
endpoint will receive a POST request with a body:
{
"meta": {
"jobId": "a9673347-8f2e-4caa-83e9-4139d7473c2f:A1",
"jobType": "sync",
},
"data": {
{
"id": "111",
"uploadId": "00000000-0000-0000-0000-000000000111",
"sku": "SKU-111",
},
{
"id": "222",
"uploadId": "00000000-0000-0000-0000-00000000222a",
"sku": "SKU-222-a",
},
{
"id": "222",
"uploadId": "00000000-0000-0000-0000-00000000222b",
"sku": "SKU-222-b",
},
{
"id": "333",
"uploadId": false,
}
}
}
After decoding it you can transform it to a helper model:
use CappasitySDK\Client\Model\Callback\Process\JobsPushResultPost;
/** @var JobsPushResultPost\SyncDataItem[]|JobsPushResultPost $matches */
$matches = JobsPushResultPost::fromCallbackBody($requestBody);
foreach ($matches as $match) {
// Handle sync item
}
Collect data as described above and register a synchronization job.
use CappasitySDK\Client\Model\Request;
$registerSyncJobId = $client
->registerSyncJob(Request\Process\JobsRegisterSyncPost::fromData(
$collectedItems,
'pull'
))
->getBodyData()
->getId();
The results are stored for 24 hours or until the acknowledgement.
To track all submitted jobs you can get a list of them, so you could get its IDs and statuses. Call the
getPullJobList() method. Job lifecycle goes through three statuses: queued
, processing
and success
. Once the job status is success
, you should request the results.
getPullJobResult() returns the result but does not erase it. You should implicitly acknowledge the result after you handle it successfully. If there is no result yet, then 404 will be returned.
You can calculate the difference between current state and received results and update changed items. Make sure you store matched View IDs because you will need it later.
acknowledgePullJobList() erases job results. You also can acknowledge multiple jobs by IDs at the same time.
Cappasity stores the matches of your inner product IDs and Cappasity View IDs in order to provide you only those items which have changed.
When your product database state changes – you have a new product, some product is updated, then you should collect
relevant data scope and register the synchronization job again.
This time you should also provide previously matched Cappasity View IDs passing it as capp
parameter value. If
something has changed – 3D View has been deleted, another 3D View has been assigned to previously matched SKU, or a new
one has been uploaded – the job will result in a diff.
Collected data example:
$collectedItems = [
[
'id' => '111',
'aliases' => ['SKU-111'],
'capp' => '00000000-0000-0000-0000-000000000111',
],
[
'id' => '222',
'aliases' => ['SKU-222-a'],
'capp' => '00000000-0000-0000-0000-00000000222a',
],
[
'id' => '222',
'aliases' => ['SKU-222-b'],
'capp' => '00000000-0000-0000-0000-222bbb222bbb',
],
[
'id' => '333',
'aliases' => ['SKU-333'],
],
]
Assuming that:
- View with ID
00000000-0000-0000-0000-000000000111
still has SKUSKU-111
- View with ID
00000000-0000-0000-0000-00000000222a
has been deleted - New view with ID
00000000-0000-0000-0000-222bbb222bbb
has been created and has SKUSKU-222-b
,00000000-0000-0000-0000-00000000222b
has no SKU - New view with ID
00000000-0000-0000-0000-000000000333
has been created and has SKUSKU-333
Then if you receive results via the callback it will receive a POST request with a body:
{
"meta": {
"jobId": "a9673347-8f2e-4caa-83e9-4139d7473c2f:A1",
"jobType": "sync",
},
"data": {
{
"id": "222",
"uploadId": false,
"sku": "SKU-222-a",
"capp": "00000000-0000-0000-0000-00000000222a" // it means that in past `SKU-222-a` was assigned to View with this ID
},
{
"id": "222",
"uploadId": "00000000-0000-0000-0000-222bbb222bbb",
"sku": "SKU-222-b",
},
{
"id": "333",
"uploadId": "00000000-0000-0000-0000-000000000333",
}
}
}
Notice that there is no match for SKU-111
because you get the diff only. What if you
still want to get it?
In case you need to resynchronize your product database or a single item just don't send the capp
IDs when you register
the synchronization job.
Most likely, you are going to reach sync items rate limit.
- Maximum of 500 items
To register a bigger collection, split your items into several jobs.
- The maximum total number of items in all jobs registered for last 24 hours depends on your account plan, 10000 items at least.
Keep track of registered items not to overflow the limit and defer registering new jobs if needed, especially if you are used to operate with huge collections. For now, we don't provide current limit state and remaining items to sync. Consider retrying requests failed due to rate limit and use exponential backoff to reduce request count.
- Maximum of 1000 requests per 10 seconds
- Maximum of 60 new connections per 3 seconds
- Maximum of 30 active connections in total
Consider connection reuse.
Now you have all necessary Cappasity 3D View IDs.
Use them to render an iFrame with EmbedRenderer
helper class.
Add the following script tag to the pages with Cappasity 3D Views:
<script async src=”https://api.cappasity.com/api/player/cappasity-ai” />
It will collect and send Cappasity 3D View analytics.