{"id":21478445,"url":"https://github.com/ripe-tech/ripe-sdk","last_synced_at":"2025-07-15T11:30:58.660Z","repository":{"id":25697797,"uuid":"78121888","full_name":"ripe-tech/ripe-sdk","owner":"ripe-tech","description":"The public Javascript SDK for RIPE Core","archived":false,"fork":false,"pushed_at":"2024-01-02T14:17:33.000Z","size":4458,"stargazers_count":8,"open_issues_count":3,"forks_count":4,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-10T08:38:07.530Z","etag":null,"topics":["library","ripe","sdk","vanilla-javascript"],"latest_commit_sha":null,"homepage":"https://www.platforme.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ripe-tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-05T14:54:16.000Z","updated_at":"2023-10-10T09:34:25.000Z","dependencies_parsed_at":"2023-01-16T22:02:27.528Z","dependency_job_id":"399feb55-0e41-4c8c-8b17-ca386b79202c","html_url":"https://github.com/ripe-tech/ripe-sdk","commit_stats":{"total_commits":3139,"total_committers":24,"mean_commits":"130.79166666666666","dds":0.7378145906339599,"last_synced_commit":"3b771fc6eaf0c7ee7656d415f9ba36ab79ab1ccb"},"previous_names":[],"tags_count":306,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripe-tech%2Fripe-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripe-tech%2Fripe-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripe-tech%2Fripe-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripe-tech%2Fripe-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ripe-tech","download_url":"https://codeload.github.com/ripe-tech/ripe-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225629748,"owners_count":17499295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","ripe","sdk","vanilla-javascript"],"created_at":"2024-11-23T11:18:20.652Z","updated_at":"2024-11-23T11:18:21.209Z","avatar_url":"https://github.com/ripe-tech.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003e\u003ca href=\"https://tech.platforme.com\"\u003e\u003cimg src=\"res/logo.svg\" alt=\"RIPE SDK\" height=\"60\" style=\"height: 60px;\"\u003e\u003c/a\u003e\u003c/h1\u003e\n\nThe public SDK for [RIPE Core](https://github.com/ripe-tech/ripe-core) written in vanilla ECMAScript v6.\n\n## Installation\n\nWhen using RIPE SDK in a web context, include it via a `\u003cscript\u003e` tag, such as:\n\n```html\n\u003cscript type=\"text/javascript\" src=\"https://sdk.platforme.com/js/ripe.min.js\"\u003e\u003c/script\u003e\n```\n\nWhen using RIPE SDK in a NPM compatible context, use as such:\n\n```bash\nnpm install --save ripe-sdk\n```\n\nIf using the configurator include the needed CSS tag, such as:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"https://sdk.platforme.com/css/ripe.css\"\u003e\n```\n\n## 1. Initialization\n\nAs a starting point, you need to provide the `brand` and `model` of your customizable product.\nYou may also pass an [`options`](#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.\n\n```javascript\nvar ripe = new Ripe({\n    brand: brand,\n    model: model,\n    variant: variant,\n    url: url,\n    currency: currency,\n    country: country,\n    dku: dku\n});\n```\n\n## 2. Events\n\nAfter initializing the Ripe object you should subscribe to the available events so you can easily respond and update your UI.\n\n### Ready\n\nTriggered when all of the async operations related with the instance setup are complete.\n\n```javascript\nripe.bind(\"ready\", function() {\n    doSomeStuff();\n});\n```\n\n### Update\n\nTriggered whenever there is a customization change (eg: the color of a part is changed).\n\n```javascript\nripe.bind(\"update\", function() {\n    updateUI();\n});\n```\n\n### Price\n\nNotifies you when the price of the customization changes.\n\n```javascript\nripe.bind(\"price\", function(value) {\n    var price = document.getElementById(\"price\");\n    price.innerHTML = value.total.price_final + \" \" + value.total.currency;\n});\n```\n\n### Config\n\nCalled 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.\n\n```javascript\nripe.bind(\"config\", function(config) {\n    var parts = config.parts;\n});\n```\n\n### Combinations\n\nCalled when the possible customization combinations of the product are loaded. Each combination is a triplet formed by `part`, `material` and `color`.\n\n```javascript\nripe.bind(\"combinations\", function(value) {\n    for (var index = 0; index \u003c value.length; index++) {\n        var triplet = value[index];\n        var part = triplet[0];\n        var material = triplet[1];\n        var color = triplet[2];\n        // (...)\n    }\n});\n```\n\n### Parts\n\nNotifies you when all the product's parts have changed.\n\n```javascript\nripe.bind(\"parts\", function(parts) {\n    parts \u0026\u0026 showPartsPicker(parts);\n});\n```\n\nYou can also be notified when a part is selected.\n\n```javascript\nripe.bind(\"selected_part\", function(part) {\n    console.log(\"Part selected: \", part);\n});\n```\n\n### Frames\n\nTriggered whenever there is a frame change.\n\n```javascript\nconfigurator.bind(\"changed_frame\", function(frame) {\n    frame === \"top\" \u0026\u0026 disableButton(\"top-view-button\");\n});\n```\n\n## 3. Product visualization\n\nUsually the product has 24 lateral frames, plus a top and bottom view.\nTo display any frame of the product you can use the `bindImage` function to automatically update an `\u003cimg\u003e` element. This method also contains an `options` parameter.\nSubscribe to the event `loaded` and you will know when your image is loaded.\nFinally, after the initial binding of the frames you should call the `load` function for the initial update.\n\n```javascript\nvar element = document.getElementById(\"frame-0\")\nvar image = ripe.bindImage(element, {\n    frame: \"side-0\"\n});\n\nimage.bind(\"loaded\", function(frame) {\n    console.log(\"frame \" + frame + \" loaded\")\n});\n\nripe.load();\n```\n\nWhenever you want to set a new image frame, you only have to call `setFrame` function.\n\n```javascript\nimage.setFrame(\"side-3\");\n```\n\n## 4. Product customization\n\nYou can change a part of your product by using the `setPart` function.\nAlternatively, multiple parts can be changed at once with `setParts`.\n\n```javascript\nripe.setPart(part, material, color);\nripe.setParts([\n    [part, material, color],\n    [part, material, color]\n]);\n```\n\nTo 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.\n\n```javascript\nif (ripe.canUndo()) {\n    ripe.undo();\n}\n\nif (ripe.canRedo()) {\n    ripe.redo();\n}\n```\n\n### Getters\n\nIf you need to explicitly retrieve the product's customization information you can use the following methods:\n\n* `getConfig`: to get information about the product's model.\n* `getCombinations`: to get all the customization options for products without any restrictions applied.\n* `getDefaults`: to get the product's default customization.\n* `getFrames`: to get all the product's frames.\n* `getPrice`: to get the product's pricing information.\n* `getFactory`: to get the factory information where the model is made, specifically its name and the estimated production time in days.\n\nThese functions receive a callback function as a parameter as shown below:\n\n```javascript\nripe.getPrice(function(value) {\n    var price = document.getElementById(\"price\");\n    price.innerHTML = value.total.price_final + \" \" + value.total.currency;\n});\n```\n\n## 5. Product personalization\n\nTo display a frame with initials you can use the bindImage function by setting the parameter `showInitials` as `true` on the options map.\nThe initials are set on the `Ripe` object with the `setInitials` function which accepts `initials` and `engraving` as parameters.\nIf 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.\n\n```javascript\nripe.setInitials(\"SW\", \"metal_gold\");\n\nripe.bindImage(document.getElementById(\"frame-initials\"), {\n    showInitials: true\n});\n```\n\n## 6. Product interaction\n\nTo provide an interactive product visualization you simply need to pass a `\u003cdiv\u003e` element to the method `bindConfigurator`.\nSubscribe to the event `loaded` and you will know when your configurator is loaded.\n\nThis element supports the following methods:\n\n| Method         | Params                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Description                                                      |\n| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |\n| `changeFrame`  | \u003cul\u003e\u003cli\u003e`frame` *(string), named frame defined in the \"view-position\" format. Eg.: \"side-0\"*\u003c/li\u003e\u003cli\u003e`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\u003c/li\u003e\u003c/ul\u003e | Displays a new frame, with an animation from the starting frame. |\n| `highlight`    | \u003cul\u003e\u003cli\u003e`part` *(string), named part*\u003c/li\u003e\u003cli\u003e`options` *(JSON object with optional fields)*\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                                                                                                                                                                      | Highlights a product's part.                                     |\n| `lowlight`     | \u003cul\u003e\u003cli\u003e`options` *(JSON object with optional fields)*\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                                                                                                                                                                                                            | Removes any highlight from the product.                          |\n| `selectPart`   | \u003cul\u003e\u003cli\u003e`part` *(string), named part*\u003c/li\u003e\u003cli\u003e`options` *(JSON object with optional fields)*\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                                                                                                                                                                      | Selects a given product's part.                                  |\n| `deselectPart` | \u003cul\u003e\u003cli\u003e`part` *(string), named part*\u003c/li\u003e\u003cli\u003e`options` *(JSON object with optional fields)*\u003c/li\u003e\u003c/ul\u003e                                                                                                                                                                                                                                                                                                                                                                                                      | Removes selection from a given product's part.                   |\n\nThis element supports the following events:\n\n| Event           | Description                                                                                                                        |\n| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `ready`         | Triggered upon first loading of the model's internal frame structure (once per model load).                                        |\n| `loaded`        | Triggered when the configurator finishes loading all of the internal frames, and is ready for interaction (once per part setting). |\n| `changed_frame` | Raises whenever there's a rotation in the configurator viewport (viewable frame has changed).                                      |\n\n```javascript\nvar element = document.getElementById(\"config\");\nvar configurator = ripe.bindConfigurator(element, {});\n\nconfigurator.bind(\"loaded\", function() {\n    this.changeFrame(\"side-11\", {\n        duration: 500\n    });\n});\n```\n\n## 7. Plugins\n\n### Part synchronization\n\nIf 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.\n\n```javascript\nripe.getConfig(function(config) {\n    var syncRules = config.sync;\n    var syncPlugin = new Ripe.plugins.SyncPlugin(syncRules);\n    ripe.addPlugin(syncPlugin);\n});\n```\n\n### Part restrictions\n\nTo 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.\nTo 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.\n\n```javascript\nripe.getConfig(function(config) {\n    var restrictionRules = config.restrictions;\n    var restrictionsPlugin = new Ripe.plugins.RestrictionsPlugin(restrictionRules);\n    ripe.addPlugin(restrictionsPlugin);\n    restrictionsPlugin.bind(\"restrictions\", function(changes, part) {});\n});\n```\n\n## 8. Sizes\n\nIf 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`.\nTo 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.\n\n* `sizeToNative(scale, value, gender)`\n* `nativeToSize(scale, value, gender)`\n* `sizeToNativeB(scales, values, genders)`\n* `nativeToSizeB(scales, values, genders)`\n\n## 9. Authentication\n\nWhen 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`:\n\n```javascript\nif (ripe.isOAuthPending()) {\n    ripe.oauth({\n        clientId: clientId,\n        clientSecret: clientSecret,\n        scope: [\"admin\"]\n    });\n}\n```\n\n## Appendix\n\n### Options\n\n| Name                      | Type               | Description                                                                                                                                                                                |\n| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `backgroundColor`         | *string*           | RGB format color value of the background ( no need to pass the \"#\" signal ). No background by default. Example: \"cccccc\".                                                                  |\n| `country`                 | *string*           | Two letters standard country codes defined in *ISO 3166-1 alpha-2* codes. \"US\" by default. Example: \"PT\".                                                                                  |\n| `currency`                | *string*           | Standard currency codes defined in *ISO 4217* codes. \"USD\" by default. Example: \"EUR\".                                                                                                     |\n| `frames`                  | *array of strings* | All the frames to be used in the customization. Example: [\"top\", \"bottom\", \"1\", \"2\"].                                                                                                      |\n| `format`                  | *string*           | One of the valid image formats: 'lossless', 'lossful', 'jpeg', 'webp', 'sgi' or 'png'. \"null\" by default.                                                                                  |\n| `maskDuration`            | *number*           | Specifies how many milliseconds the mask animation takes to complete. 150 by default.                                                                                                      |\n| `maskOpacity`             | *number*           | Specifies the opacity value of the the masks used to highlight/select parts. 0.4 by default.                                                                                               |\n| `maxSize`                 | *number*           | Maximum value for frame image size. 1000px by default.                                                                                                                                     |\n| `noCombinations`          | *boolean*          | Defines if the combinations are loaded or not. False (loading) by default.                                                                                                                 |\n| `noDefaults`              | *boolean*          | Defines if the defaults are loaded or not. False (loading) by default.                                                                                                                     |\n| `noMasks`                 | *boolean*          | Used to negate the `useMasks` option.                                                                                                                                                      |\n| `noPrice`                 | *boolean*          | Used to negate the `usePrice` option.                                                                                                                                                      |\n| `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\" }, ... }`. |\n| `remoteCalls`             | *boolean*          | Activates the remote calls functionality executed by several workflows. True by default.                                                                                                   |\n| `remoteOnConfig`          | *boolean*          | Activates the remote execution of the model's logic on config updates. True by default.                                                                                                    |\n| `remoteOnPart`            | *boolean*          | Activates the remote execution of the model's logic on parts updates. True by default.                                                                                                     |\n| `remoteOnInitials`        | *boolean*          | Activates the remote execution of the model's logic on initials updates. True by default.                                                                                                  |\n| `sensitivity`             | *string*           | Defines the degree of sensitivity of the dragging interaction. 40 by default.                                                                                                              |\n| `size`                    | *number*           | Initial size value of a frame image that is going to be composed. By default it's 1000px.                                                                                                  |\n| `url`                     | *string*           | The base `url` of the server where the product is configured.                                                                                                                              |\n| `variant`                 | *string*           | Variant of the customizable product.                                                                                                                                                       |\n| `version`                 | *string*           | The version of the build of the customizable product.                                                                                                                                      |\n| `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.                                              |\n| `useMasks`                | *boolean*          | Enables masks on selection/highlight. True by default.                                                                                                                                     |\n| `usePrice`                | *boolean*          | Enables the fetch price feature every time a new part is set. True by default.                                                                                                             |\n| `useSync`                 | *boolean*          | Enables the part synchronization feature. False by default.                                                                                                                                |\n| `useInitialsBuilderLogic` | *boolean*          | Enables the usage of the client-side initials builder logic defined in the 3DB, instead of the default one. True by default.                                                               |\n\n## Browser Support\n\nDesktop:\n\n* ≥ Chrome v23 (V8)\n* ≥ Firefox v21 (SpiderMonkey)\n* ≥ Safari v6 (Nitro)\n* ≥ Opera v12 (V8)\n* ≥ IE v11 (Chakra)\n\nMobile:\n\n* ≥ Android  4.4\n* ≥ iOS's WebKit 9\n\n## Documentation\n\nFor API reference documentation follow [ripe-sdk-docs.platforme.com](https://ripe-sdk-docs.platforme.com).\n\n## License\n\nRIPE SDK is currently licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/).\n\n## Build Automation\n\n[![Build Status](https://app.travis-ci.com/ripe-tech/ripe-sdk.svg?branch=master)](https://travis-ci.com/github/ripe-tech/ripe-sdk)\n[![Build Status GitHub](https://github.com/ripe-tech/ripe-sdk/workflows/Main%20Workflow/badge.svg)](https://github.com/ripe-tech/ripe-sdk/actions)\n[![npm Status](https://img.shields.io/npm/v/ripe-sdk.svg)](https://www.npmjs.com/package/ripe-sdk)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripe-tech%2Fripe-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fripe-tech%2Fripe-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripe-tech%2Fripe-sdk/lists"}