RIPE Core 的公共 SDK 用 vanilla ECMAScript v6 编写。
1. Initialization
首先,您需要提供可定制产品的 brand
和 model
。
您还可以传递一个 options
映射来覆盖配置产品的服务器的基本 url
等参数,以及 currency
和 country
,默认情况下分别为“EUR”和“US”。
var ripe = new Ripe({
brand: brand,
model: model,
variant: variant,
url: url,
currency: currency,
country: country,
dku: dku
});
2. Events
初始化 Ripe 对象后,您应该订阅可用事件,以便轻松响应和更新您的 UI。
Ready
当与实例设置相关的所有异步操作完成时触发。
ripe.bind("ready", function() {
doSomeStuff();
});
Update
每当有自定义更改时触发(例如:更改部件的颜色)。
ripe.bind("update", function() {
updateUI();
});
Price
当定制价格发生变化时通知您。
ripe.bind("price", function(value) {
var price = document.getElementById("price");
price.innerHTML = value.total.price_final + " " + value.total.currency;
});
Config
加载新模型配置时调用。 您应该使用它来探索模型的配置数据,即:在您的 UI 上填充自定义选项时。
ripe.bind("config", function(config) {
var parts = config.parts;
});
Combinations
在加载产品的可能自定义组合时调用。 每个组合都是由 part
、material
和 color
组成的三元组。
ripe.bind("combinations", function(value) {
for (var index = 0; index < value.length; index++) {
var triplet = value[index];
var part = triplet[0];
var material = triplet[1];
var color = triplet[2];
// (...)
}
});
Parts
当产品的所有部件都发生变化时通知您。
ripe.bind("parts", function(parts) {
parts && showPartsPicker(parts);
});
您也可以在选择零件时收到通知。
ripe.bind("selected_part", function(part) {
console.log("Part selected: ", part);
});
Frames
每当有帧更改时触发。
configurator.bind("changed_frame", function(frame) {
frame === "top" && disableButton("top-view-button");
});
3. Product visualization
通常产品有 24 个横向框架,外加俯视图和仰视图。
要显示产品的任何框架,您可以使用 bindImage
函数自动更新
元素。 此方法还包含一个 options
参数。
订阅事件 loaded
,您将知道何时加载图像。
最后,在初始绑定框架后,您应该调用 load
函数进行初始更新。
var element = document.getElementById("frame-0")
var image = ripe.bindImage(element, {
frame: "side-0"
});
image.bind("loaded", function(frame) {
console.log("frame " + frame + " loaded")
});
ripe.load();
每当你想设置一个新的图像框架时,你只需要调用 setFrame
函数。
image.setFrame("side-3");
4. Product customization
您可以使用 setPart
函数更改产品的一部分。
或者,可以使用 setParts
一次更改多个部分。
ripe.setPart(part, material, color);
ripe.setParts([
[part, material, color],
[part, material, color]
]);
要撤消产品中的部分更改,您可以调用 undo
函数。 canUndo
方法也可用,因此您可以允许基于当前更改的撤消操作。 要撤销undo
操作,您可以使用redo
函数。
if (ripe.canUndo()) {
ripe.undo();
}
if (ripe.canRedo()) {
ripe.redo();
}
Getters
如果您需要显式检索产品的自定义信息,您可以使用以下方法:
getConfig
: to get information about the product's model.
getCombinations
: to get all the customization options for products without any restrictions applied.
getDefaults
: to get the product's default customization.
getFrames
: to get all the product's frames.
getPrice
: to get the product's pricing information.
getFactory
: to get the factory information where the model is made, specifically its name and the estimated production time in days.
这些函数接收回调函数作为参数,如下所示:
ripe.getPrice(function(value) {
var price = document.getElementById("price");
price.innerHTML = value.total.price_final + " " + value.total.currency;
});
5. Product personalization
要显示带有首字母的框架,您可以通过设置参数 showInitials 使用 bindImage 函数
在选项映射上为 true
。
使用 setInitials
函数在 Ripe
对象上设置首字母,该函数接受 initials
和 engraving
作为参数。
如果您的姓名缩写需要转换为不同的配置文件,您可以设置一个函数来接收 initials
和 engraving
参数,并将其转换为带有姓名缩写和配置文件数组的地图,使用setInitialsBuilder
函数。
ripe.setInitials("SW", "metal_gold");
ripe.bindImage(document.getElementById("frame-initials"), {
showInitials: true
});
6. Product interaction
要提供交互式产品可视化,您只需将
元素传递给方法 bindConfigurator
。
订阅事件 loaded
,您将知道您的配置器何时加载。
此元素支持以下方法:
Method |
Params |
Description |
changeFrame |
frame (string), named frame defined in the "view-position" format. Eg.: "side-0"options (JSON object with optional fields): duration : (number) total duration, in milliseconds, of the animation; type : (string) the animation style you want, which can be "simple" (fade in), "cross" (crossfade) or null (without any style)*; preventDrag : *(boolean)* to choose if drag actions during an animated change of frames should be ignored. "True" by default
|
displays a new frame, with an animation from the starting frame |
highlight |
part (string), named partoptions (JSON object with optional fields)
|
highlights a product's part |
lowlight |
options (JSON object with optional fields)
|
removes any highlight from the product |
selectPart |
part (string), named partoptions (JSON object with optional fields)
|
selects a given product's part |
deselectPart |
part (string), named partoptions (JSON object with optional fields)
|
removes selection from a given product's part |
此元素支持以下事件:
Event |
Description |
ready |
Triggered upon first loading of the model's internal frame structure (once per model load) |
loaded |
Triggered when the configurator finishes loading all of the internal frames, and is ready for interaction (once per part setting) |
changed_frame |
Raises whenever there's a rotation in the configurator viewport (viewable frame has changed) |
var element = document.getElementById("config");
var configurator = ripe.bindConfigurator(element, {});
configurator.bind("loaded", function() {
this.changeFrame("side-11", {
duration: 500
});
});
7. Plugins
Part synchronization
如果您的产品有同步规则,其中一组零件必须始终具有相同的材料和颜色,您可以使用 sync
插件来实现这种行为是自动的。 为此,您需要初始化接收同步规则的 SyncPlugin
,并使用 addPlugin
函数将其添加到成熟对象中。 设置新部件时,插件会检查同步规则并自动对相关部件进行必要的更改。
ripe.getConfig(function(config) {
var syncRules = config.sync;
var syncPlugin = new Ripe.plugins.SyncPlugin(syncRules);
ripe.addPlugin(syncPlugin);
});
Part restrictions
要包括对自定义体验的限制,可以使用 Restrictions
插件。 这允许设置规则声明不同部件、材料或颜色之间的某些组合是不可能的。 选择新选项时,插件将检查是否有任何其他部分受到新部分的限制,并自动将它们更改为有效选项。 该插件的用法与sync
插件类似。
要在限制导致部件更改时收到通知,请绑定到插件对象上的 restrictions
事件。 每当应用限制时,将通过发生的更改和导致它们的部分触发此事件。
ripe.getConfig(function(config) {
var restrictionRules = config.restrictions;
var restrictionsPlugin = new Ripe.plugins.RestrictionsPlugin(restrictionRules);
ripe.addPlugin(restrictionsPlugin);
restrictionsPlugin.bind("restrictions", function(changes, part) {});
});
8. Sizes
如果您需要使用 ripe-core
API 创建订单,那么您必须根据 ripe-core
原生比例设置产品尺寸。 以下方法允许您从该比例转换到该比例。 scale
是表示大小比例的字符串,value
是该比例中的数值,gender
是可以设置为 < code>female,male
或 kids
。
当您需要转换多个尺寸选项时,为了减少请求数量,您可以使用接受值数组并返回包含所有结果的数组的批量方法。
sizeToNative(scale, value, gender)
nativeToSize(scale, value, gender)
sizeToNativeB(scales, values, genders)
nativeToSizeB(scales, values, genders)
9. Authentication
当使用需要特殊权限的 API 方法时,您可以使用以下方法对您的应用程序进行身份验证:auth(username, password, callback)
,用于使用用户名和密码登录,或使用 oauth 进行 OAuth 身份验证
:
if (ripe.isOAuthPending()) {
ripe.oauth({
clientId: clientId,
clientSecret: clientSecret,
scope: ["admin"]
});
}
Appendix
Options
Name |
Type |
Description d |
backgroundColor |
string |
RGB format color value of the background ( no need to pass the "#" signal ). No background by default. Example: "cccccc". |
country |
string |
Two letters standard country codes defined in ISO 3166-1 alpha-2 codes. "US" by default. Example: "PT". |
currency |
string |
Standard currency codes defined in ISO 4217 codes. "USD" by default. Example: "EUR". |
frames |
array of strings |
All the frames to be used in the customization. Example: ["top", "bottom", "1", "2"]. |
format |
string |
One of the valid image formats: 'lossless', 'lossful', 'jpeg', 'webp', 'sgi' or 'png'. "png" by default. |
maskDuration |
number |
Specifies how many milliseconds the mask animation takes to complete. 150 by default. |
maskOpacity |
number |
Specifies the opacity value of the the masks used to highlight/select parts. 0.4 by default. |
maxSize |
number |
Maximum value for frame image size. 1000px by default. |
noCombinations |
boolean |
Defines if the combinations are loaded or not. False (loading) by default. |
noDefaults |
boolean |
Defines if the defaults are loaded or not. False (loading) by default. |
noMasks |
boolean |
Used to negate the useMasks option. |
noPrice |
boolean |
Used to negate the usePrice option. |
parts |
JSON Object |
Defines the product initial parts. Each key is a part's name built with color and material information. Example: var parts = { "sole": { "material": "nappa", "color": "white" }, ... } . |
remoteCalls |
boolean |
Activates the remote calls functionality executed by several workflows. True by default. |
remoteOnConfig |
boolean |
Activates the remote execution of the model's logic on config updates. True by default. |
remoteOnPart |
boolean |
Activates the remote execution of the model's logic on parts updates. True by default. |
remoteOnInitials |
boolean |
Activates the remote execution of the model's logic on initials updates. True by default. |
sensitivity |
string |
Defines the degree of sensitivity of the dragging interaction. 40 by default. |
size |
number |
Initial size value of a frame image that is going to be composed. By default it's 1000px. |
url |
string |
The base url of the server where the product is configured. |
variant |
string |
Variant of the customizable product. |
version |
string |
The version of the build of the customizable product. |
useChain |
boolean |
Determines if a chain based loading should be used for the pre-loading process of the various image resources to be loaded. False by default. |
useMasks |
boolean |
Enables masks on selection/highlight. True by default. |
usePrice |
boolean |
Enables the fetch price feature every time a new part is set. True by default. |
useSync |
boolean |
Enables the part synchronization feature. False by default. |
Browser Support
桌面:
- ≥ Chrome v23 (V8)
- ≥ Firefox v21 (SpiderMonkey)
- ≥ Safari v6 (Nitro)
- ≥ Opera v12 (V8)
- ≥ IE v11 (Chakra)
移动:
- ≥ Android 4.4
- ≥ iOS's WebKit 9
Documentation
有关 API 参考文档,请访问 ripe-sdk-docs.platforme.com。
License
RIPE SDK 目前根据 Apache License, Version 2.0 获得许可。
Build Automation
The public SDK for RIPE Core written in vanilla ECMAScript v6.
1. Initialization
As a starting point, you need to provide the brand
and model
of your customizable product.
You may also pass an options
map to override parameters like the base url
of the server where the product is configured, as well as currency
and country
, which are 'EUR' and 'US' respectively by default.
var ripe = new Ripe({
brand: brand,
model: model,
variant: variant,
url: url,
currency: currency,
country: country,
dku: dku
});
2. Events
After initializing the Ripe object you should subscribe to the available events so you can easily respond and update your UI.
Ready
Triggered when all of the async operations related with the instance setup are complete.
ripe.bind("ready", function() {
doSomeStuff();
});
Update
Triggered whenever there is a customization change (eg: the color of a part is changed).
ripe.bind("update", function() {
updateUI();
});
Price
Notifies you when the price of the customization changes.
ripe.bind("price", function(value) {
var price = document.getElementById("price");
price.innerHTML = value.total.price_final + " " + value.total.currency;
});
Config
Called when a new model configuration has been loaded. You should use this to explore the model's configuration data, ie: when populating the customization options on your UI.
ripe.bind("config", function(config) {
var parts = config.parts;
});
Combinations
Called when the possible customization combinations of the product are loaded. Each combination is a triplet formed by part
, material
and color
.
ripe.bind("combinations", function(value) {
for (var index = 0; index < value.length; index++) {
var triplet = value[index];
var part = triplet[0];
var material = triplet[1];
var color = triplet[2];
// (...)
}
});
Parts
Notifies you when all the product's parts have changed.
ripe.bind("parts", function(parts) {
parts && showPartsPicker(parts);
});
You can also be notified when a part is selected.
ripe.bind("selected_part", function(part) {
console.log("Part selected: ", part);
});
Frames
Triggered whenever there is a frame change.
configurator.bind("changed_frame", function(frame) {
frame === "top" && disableButton("top-view-button");
});
3. Product visualization
Usually the product has 24 lateral frames, plus a top and bottom view.
To display any frame of the product you can use the bindImage
function to automatically update an <img>
element. This method also contains an options
parameter.
Subscribe to the event loaded
and you will know when your image is loaded.
Finally, after the initial binding of the frames you should call the load
function for the initial update.
var element = document.getElementById("frame-0")
var image = ripe.bindImage(element, {
frame: "side-0"
});
image.bind("loaded", function(frame) {
console.log("frame " + frame + " loaded")
});
ripe.load();
Whenever you want to set a new image frame, you only have to call setFrame
function.
image.setFrame("side-3");
4. Product customization
You can change a part of your product by using the setPart
function.
Alternatively, multiple parts can be changed at once with setParts
.
ripe.setPart(part, material, color);
ripe.setParts([
[part, material, color],
[part, material, color]
]);
To undo part changes in the product you can call the undo
function. The method canUndo
is also available so you can allow the undo operation based on the current changes. To reverse an undo
operation you can use the redo
function.
if (ripe.canUndo()) {
ripe.undo();
}
if (ripe.canRedo()) {
ripe.redo();
}
Getters
If you need to explicitly retrieve the product's customization information you can use the following methods:
getConfig
: to get information about the product's model.
getCombinations
: to get all the customization options for products without any restrictions applied.
getDefaults
: to get the product's default customization.
getFrames
: to get all the product's frames.
getPrice
: to get the product's pricing information.
getFactory
: to get the factory information where the model is made, specifically its name and the estimated production time in days.
These functions receive a callback function as a parameter as shown below:
ripe.getPrice(function(value) {
var price = document.getElementById("price");
price.innerHTML = value.total.price_final + " " + value.total.currency;
});
5. Product personalization
To display a frame with initials you can use the bindImage function by setting the parameter showInitials
as true
on the options map.
The initials are set on the Ripe
object with the setInitials
function which accepts initials
and engraving
as parameters.
If your initials require a transformation to different profiles you can set a function that receives the initials
and engraving
parameters and transforms it into a map with initials and an array of profiles using the setInitialsBuilder
function.
ripe.setInitials("SW", "metal_gold");
ripe.bindImage(document.getElementById("frame-initials"), {
showInitials: true
});
6. Product interaction
To provide an interactive product visualization you simply need to pass a <div>
element to the method bindConfigurator
.
Subscribe to the event loaded
and you will know when your configurator is loaded.
This element supports the following methods:
Method |
Params |
Description |
changeFrame |
frame (string), named frame defined in the "view-position" format. Eg.: "side-0"options (JSON object with optional fields): duration : (number) total duration, in milliseconds, of the animation; type : (string) the animation style you want, which can be "simple" (fade in), "cross" (crossfade) or null (without any style)*; preventDrag : *(boolean)* to choose if drag actions during an animated change of frames should be ignored. "True" by default
|
displays a new frame, with an animation from the starting frame |
highlight |
part (string), named partoptions (JSON object with optional fields)
|
highlights a product's part |
lowlight |
options (JSON object with optional fields)
|
removes any highlight from the product |
selectPart |
part (string), named partoptions (JSON object with optional fields)
|
selects a given product's part |
deselectPart |
part (string), named partoptions (JSON object with optional fields)
|
removes selection from a given product's part |
This element supports the following events:
Event |
Description |
ready |
Triggered upon first loading of the model's internal frame structure (once per model load) |
loaded |
Triggered when the configurator finishes loading all of the internal frames, and is ready for interaction (once per part setting) |
changed_frame |
Raises whenever there's a rotation in the configurator viewport (viewable frame has changed) |
var element = document.getElementById("config");
var configurator = ripe.bindConfigurator(element, {});
configurator.bind("loaded", function() {
this.changeFrame("side-11", {
duration: 500
});
});
7. Plugins
Part synchronization
If your product has synchronization rules, where a set of parts must always have the same material and color, you can use the sync
plugin to have this behavior automatically. To do this you need to initialize the SyncPlugin
which receives the synchronization rules and add it to the ripe object using the addPlugin
function. When a new part is set, the plugin checks the synchronization rules and automatically makes the necessary changes to the related parts.
ripe.getConfig(function(config) {
var syncRules = config.sync;
var syncPlugin = new Ripe.plugins.SyncPlugin(syncRules);
ripe.addPlugin(syncPlugin);
});
Part restrictions
To include restrictions to the customization experience the Restrictions
plugin is available. This allow setting rules that declare that certain combinations between different parts, materials or colors are not possible. When a new option is selected, the plugin will check if any of the other parts has become restricted by the new part and change them to a valid option automatically. The usage of this plugin is similar to the sync
plugin.
To be notified when a restriction causes parts to be changed, bind to the restrictions
event on the plugin object. Whenever the restrictions are applied, this event will be triggered with the changes that ocurred and the part that caused them.
ripe.getConfig(function(config) {
var restrictionRules = config.restrictions;
var restrictionsPlugin = new Ripe.plugins.RestrictionsPlugin(restrictionRules);
ripe.addPlugin(restrictionsPlugin);
restrictionsPlugin.bind("restrictions", function(changes, part) {});
});
8. Sizes
If you need to create an order using the ripe-core
API then you have to set the size of the product according to the ripe-core
native scale. The following methods allow you to convert from and to that scale. scale
is a string that represents the size scale, value
is the numeric value in that scale and gender
is a string that can be set to female
, male
or kids
.
To reduce the number of requests when you need to convert several size options you can use the bulk methods that accept an array of values and return an array with all the results.
sizeToNative(scale, value, gender)
nativeToSize(scale, value, gender)
sizeToNativeB(scales, values, genders)
nativeToSizeB(scales, values, genders)
9. Authentication
When using API methods that require special permissions you can use the following methods to authenticate your application: auth(username, password, callback)
, for login with username and password, or OAuth authentication with oauth
:
if (ripe.isOAuthPending()) {
ripe.oauth({
clientId: clientId,
clientSecret: clientSecret,
scope: ["admin"]
});
}
Appendix
Options
Name |
Type |
Description d |
backgroundColor |
string |
RGB format color value of the background ( no need to pass the "#" signal ). No background by default. Example: "cccccc". |
country |
string |
Two letters standard country codes defined in ISO 3166-1 alpha-2 codes. "US" by default. Example: "PT". |
currency |
string |
Standard currency codes defined in ISO 4217 codes. "USD" by default. Example: "EUR". |
frames |
array of strings |
All the frames to be used in the customization. Example: ["top", "bottom", "1", "2"]. |
format |
string |
One of the valid image formats: 'lossless', 'lossful', 'jpeg', 'webp', 'sgi' or 'png'. "png" by default. |
maskDuration |
number |
Specifies how many milliseconds the mask animation takes to complete. 150 by default. |
maskOpacity |
number |
Specifies the opacity value of the the masks used to highlight/select parts. 0.4 by default. |
maxSize |
number |
Maximum value for frame image size. 1000px by default. |
noCombinations |
boolean |
Defines if the combinations are loaded or not. False (loading) by default. |
noDefaults |
boolean |
Defines if the defaults are loaded or not. False (loading) by default. |
noMasks |
boolean |
Used to negate the useMasks option. |
noPrice |
boolean |
Used to negate the usePrice option. |
parts |
JSON Object |
Defines the product initial parts. Each key is a part's name built with color and material information. Example: var parts = { "sole": { "material": "nappa", "color": "white" }, ... } . |
remoteCalls |
boolean |
Activates the remote calls functionality executed by several workflows. True by default. |
remoteOnConfig |
boolean |
Activates the remote execution of the model's logic on config updates. True by default. |
remoteOnPart |
boolean |
Activates the remote execution of the model's logic on parts updates. True by default. |
remoteOnInitials |
boolean |
Activates the remote execution of the model's logic on initials updates. True by default. |
sensitivity |
string |
Defines the degree of sensitivity of the dragging interaction. 40 by default. |
size |
number |
Initial size value of a frame image that is going to be composed. By default it's 1000px. |
url |
string |
The base url of the server where the product is configured. |
variant |
string |
Variant of the customizable product. |
version |
string |
The version of the build of the customizable product. |
useChain |
boolean |
Determines if a chain based loading should be used for the pre-loading process of the various image resources to be loaded. False by default. |
useMasks |
boolean |
Enables masks on selection/highlight. True by default. |
usePrice |
boolean |
Enables the fetch price feature every time a new part is set. True by default. |
useSync |
boolean |
Enables the part synchronization feature. False by default. |
Browser Support
Desktop:
- ≥ Chrome v23 (V8)
- ≥ Firefox v21 (SpiderMonkey)
- ≥ Safari v6 (Nitro)
- ≥ Opera v12 (V8)
- ≥ IE v11 (Chakra)
Mobile:
- ≥ Android 4.4
- ≥ iOS's WebKit 9
Documentation
For API reference documentation follow ripe-sdk-docs.platforme.com.
License
RIPE SDK is currently licensed under the Apache License, Version 2.0.
Build Automation