Getting Started¶
How to generate smartlinks outside of the Argo manager¶
This document is a quick introduction on how you can generate smartlinks outside of the ARGOflow manager.
As a reminder, a smartlink (sometimes called an augmented document) is an URL that when opened in the browser will display your PDF in a reader with an additional layer of interactivity that you can design according to your communication objectives or business needs.
You can do so by either using our APIs or using the batch mode. Both methods will be detailed in this document.
In most cases, the batch mode is what you need for production : it is much faster and better suited for production use.
API usage : smartlink creation¶
When using the API you need to follow the following steps to create a smartlink that you can then share with your customers.
- Select one of your folders
- Upload a pdf in that folder
- Create a smartlink on that pdf
- Create assets in this smartlink
Most of our API calls can be tested on our swagger interface : https://dev-apicreator.argoflow.io/swagger/#/
Step 0 : Authentification¶
We use basic authentication : https://docs.ar-go.co/developers/apis/argoflow/gettingstarted/
Step 1 : Folder selection or creation¶
General information¶
A smartlink or pdf needs to be stored in a folder to be specified.
Thus the first step is to select a folder in which you want to work.
You can use the folder APIs to list the existing folders or create one.
Example of API call¶
Example to list all the folders of your organization :
Curl¶
curl -X GET "https://apicreator.ARGOflow.io/folder" -H "accept: */*" -H "Authorization: Basic cGllcnJlQGFyLWdvLmNvOjM4X2FubXXX"
Server response¶
{
code : 200,
details :
[ \
{ \
"readOnly": false, \
"_folder": null, \
"_organization": "5da8bdd0ca26fb0db035f451", \
"name": "/", \
"created": "2019-10-17T19:15:28.030Z", \
"updated": "2019-10-17T19:15:28.030Z", \
"id": "5da8bdd0ca26fb0db035f452" \
}, \
{ \
"readOnly": true, \
"_folder": "5da8bdd0ca26fb0db035f452", \
"_organization": "5da8bdd0ca26fb0db035f451", \
"name": "Unclassified", \
"created": "2019-10-17T19:15:28.032Z", \
"updated": "2019-10-17T19:15:28.032Z", \
"id": "5da8bdd0ca26fb0db035f453" \
} \
]
}
Step 2 : Content (Document) creation¶
General information¶
Once you have picked the folder you can now upload a document (a pdf) in it.
It’s important to be reminded that as per ARGO API definition a Content(Document) is the PDF file that you will upload to the platform before you augment it.
Once uploaded you should get a Content Id and see the new Content in the Folder you selected above.
Example of API call¶
Here we create in folder 605c7cd8f453c80049ca6742
Curl¶
curl --location --request POST 'https://apicreator.argoflow.io/content' \
--header 'Authorization: Basic bWljaGFlbEBhci1nby5jbzpBUkduemVIb3JzZXXX' \
--form 'file=@"/Users/[...]/BasePDF/BasePDF_01.pdf"' \
--form 'folder="605c7cd8f453c80049ca6742"' \
--form 'title="test.pdf"'
Server response¶
{
code : 200,
details:{
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_5.png?1617960183690" \
], \
"pagesWidth": [ \
562, \
566, \
566, \
566, \
566 \
], \
"pagesHeight": [ \
800, \
800, \
800, \
800, \
800 \
], \
"created": "2021-04-09T09:23:03.665Z", \
"updated": "2021-04-09T09:23:03.665Z", \
"title": "test.pdf", \
"_folder": "605c7cd8f453c80049ca6742", \
"_organization": "5da8bdd0ca26fb0db035f451", \
"_member": "5e8350da6728464013e4e59f", \
"ip": "162.158.22.140", \
"filename": "BasePDF_01.pdf", \
"filesize": 625565, \
"mimetype": "application/pdf", \
"original_url": "https://conv.argoflow.io/60701cf7e176bf00492a6f9a_original", \
"pdf_url": "https://conv.argoflow.io/60701cf7e176bf00492a6f9a.pdf", \
"id": "60701cf7e176bf00492a6f9a" \
}
}
NB : id of the content is 60701cf7e176bf00492a6f9a
Step 3 : Smartlink creation¶
General information¶
You can now create a new Smartlink based on the above created Content(Document).
You will need to specify Folder id and Document id.
You can observe that in the response that the API returns a long list of variables that can be used to activate numerous functionalities, we will not detail them in this document.
It’s important to note that by default a smartlink is empty of assets. You can create them afterward (Step 4).
Example of API call¶
Curl¶
curl -X POST "https://apicreator.ARGOflow.io/document" \
--header "accept: */*" \
--header "Authorization: Basic cGllcnJlQGFyLWdvLmNvOjM4X2FubXXX" \
--header "Content-Type: multipart/form-data" \
--form "smartlinkSocialDesc=" \
--form "pdfz_version=" \
--form "pdfzPassword=" \
--form "distribution=0" \
--form "sendMailOpen=" \
--form "faviconB64=" \
--form "folder=605c7cd8f453c80049ca6742" \
--form "extractPDF=" \
--form "tracking_email=" \
--form "endDateTime=" \
--form "title=Test doc" \
--form "content=60701cf7e176bf00492a6f9a" \
--form "pdfz_settings=" \
--form "printAllowed=" \
--form "emailRequired=" \
--form "startDateTime="
Server response¶
{ code : 200,
details: {}
"nb_pages": 5, \
"pages": [], \
"pagesAR": [ \
0, \
0, \
0, \
0, \
0 \
], \
"campaignLanguage": [], \
"auras": [], \
"crops": [ \
"0 0 562 800", \
"0 0 566 800", \
"0 0 566 800", \
"0 0 566 800", \
"0 0 566 800" \
], \
"arts": [ \
"0 0 562 800", \
"0 0 566 800", \
"0 0 566 800", \
"0 0 566 800", \
"0 0 566 800" \
], \
"book_id": 0, \
"status": "DONE", \
"ar_multi_language": false, \
"ar_multi_language_list": [], \
"ar_default_language": 0, \
"pdfz_version": "default", \
"pdfa_password": "", \
"pdfz_password": "", \
"google_analytic": "", \
"firstPage": "", \
"publication": "", \
"edition": "", \
"pivotviewer": false, \
"pixmax": "1100", \
"pixmargin": "0", \
"t5": "60", \
"dotiles": "false", \
"vgw": "10.0", \
"vgwref": "1000", \
"vgwmin": "300", \
"vmargel": "0.0", \
"vmarger": "0.0", \
"vmargol": "0.0", \
"vmargor": "0.0", \
"title": "Test doc", \
"pdfzSize": 0, \
"pdfzGzipSize": 0, \
"pdfzDeflateSize": 0, \
"cloud": 0, \
"error": [], \
"distribution": 0, \
"activated": true, \
"publish": false, \
"aura2asset": false, \
"callback_post": "", \
"tracking_email": "", \
"subDomain": "argo", \
"smartlinkSocialDesc": "", \
"faviconB64": "", \
"ar_content": "2", \
"_bear_account": null, \
"username": "Michael Merlange", \
"_organization": "5da8bdd0ca26fb0db035f451", \
"_member": "5e8350da6728464013e4e59f", \
"ip": "162.158.22.140", \
"_content": "60701cf7e176bf00492a6f9a", \
"uuid": "514c6c78-956f-493a-abd4-ae1e7aa9d3b0", \
"_folder": "605c7cd8f453c80049ca6742", \
"filesize": 625565, \
"files": { \
"upload_1": { \
"mimetype": "application/pdf", \
"filesize": 625565, \
"filename": "BasePDF_01.pdf" \
} \
}, \
"config": { \
"global": { \
"assetTrack": { \
"track": "true" \
}, \
"printTrack": { \
"track": "false" \
}, \
"pageTrack": { \
"track": "true" \
}, \
"initTrack": { \
"track": "true" \
}, \
"closeTrack": { \
"track": "true" \
}, \
"focusTrack": { \
"track": "true" \
}, \
"sendHeaders": "false", \
"sendPosition": "false", \
"printAllowed": "true", \
"displayAllowed": "true", \
"assetEnabled": "true", \
"assetInteraction": "false", \
"usageLimited": "0", \
"extractPDF": "true", \
"userStatus": 0, \
"allowRemote": "false", \
"onePageView": "true", \
"twoPageView": "false", \
"flipBookViez": "false", \
"startupView": 0, \
"thumbnails": "true", \
"summary": 0, \
"sidebarOpened": 0, \
"startDateTime": "", \
"endDateTime": "", \
"assetsOffline": "false", \
"assetsFull": "false", \
"sendMailOpen": 1, \
"sendMailCreate": "false", \
"googleAnalytic": "", \
"pdfzPassword": "false", \
"emailRequired": "false", \
"assetShowOnStartup": "true" \
}, \
"timestamp": 1617960664887, \
"pagesID": null, \
"assets": null, \
"auras": null \
}, \
"inserted": "2021-04-09T09:31:04.888Z", \
"updated": "2021-04-09T09:31:04.888Z", \
"id": "60701ed89414053015f325db", \
"pdf_url": "https://conv.argoflow.io/60701cf7e176bf00492a6f9a.pdf", \
"pdfa_url": "https://conv.argoflow.io/60701cf7e176bf00492a6f9a.pdf", \
"pdfz_url": "http://argo.argoflow.io/testdoc.sl?sl=60701ed89414053015f325db", \
"pdfzs_url": "https://argo.argoflow.io/testdoc.sl?sl=60701ed89414053015f325db", \
"pdfz_url_user": "http://argo.argoflow.io/testdoc.sl?sl=60701ed89414053015f325db&q=", \
"pdfzs_url_user": "https://argo.argoflow.io/testdoc.sl?sl=60701ed89414053015f325db&q=", \
"pagesPng": [ \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_1.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_2.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_3.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_4.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_5.png?1617960664888" \
], \
"pagesPngFull": [ \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_1.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_2.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_3.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_4.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_5.png?1617960664888" \
], \
"pagesPngPrev": [ \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_1.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_2.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_3.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_4.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_5.png?1617960664888" \
], \
"pagesPngThumb": [ \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_1.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_2.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_3.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_4.png?1617960664888", \
"https://apicreator.argoflow.io/page/60701cf7e176bf00492a6f9a_thumb_5.png?1617960664888" \
], \
"pagesWidth": [ \
"562", \
"566", \
"566", \
"566", \
"566" \
], \
"pagesHeight": [ \
"800", \
"800", \
"800", \
"800", \
"800" \
] \
}
In this example, the new smartlink’s id is 60701ed89414053015f325db
Step 4 : Asset creation¶
General information¶
Once your smartlink is created you can add assets to it. Assets are all the interactions that you add on top of your document to make it interactive, it can be images, videos or even small snippets of HTML/javascript code for more advanced features.
Assets have a rather flexible structure and the main fields are :
An asset is described as follow (not a complete description but enough is most cases) :
{
_document : id of the smartlink,
name : Human-friendly label for this asset, will be visible in editor,
page : Page number in the document,
center_x : Center of asset on x axis in % of marker Width,
center_y : Center of asset on y axis in % of marker Height,
rect: [Number,Number,], [Witdh , Height] of the Asset, in % of Width and Height,
background: resource_name,Reference to the resource image used as "icon". Will cover the whole surface defined by "rect".
}
File_name is described through a “files” object. In standard case example, with resource_name=”icon”
"files": {
"icon": {
"filename": "03_pc_ani_blue.gif",
"mimetype": "image/gif",
"filesize": 3694,
"url": "https://apicreator.argoflow.io/aura/media/606f08308b22150050bce898/icon"
}
}
NB : with same principles, you can edit an existing asset by providing its id as an input in API call.
Example of API call¶
Curl¶
curl --location --request POST 'https://apicreator.argoflow.io/asset' \
--header 'Authorization: Basic bWljaGFlbEBhci1nby5jbzpBUkduemVIb3JzZXXX' \
--form 'aura_json=@"/Users/michaelargi/Downloads/asset.json"' \
--form 'icon=@"/Users/[...].gif"' \
--form 'documentId="60701ed89414053015f325db"' \
--form 'pageNum="2"'
With asset.json being the below simple asset description
{
"api": "1.3.2",
"actions": [
{
"data": "https://dev.indv.jp/sI0n/OOq3DKm2Bi",
"type": "url"
}
],
"background": "icon",
"center_x": 47.70318021201413,
"center_y": 46.874999999999986,
"rect": [97.17314487632508, 68.75],
"center_z": 0,
"name": "demo",
"order": 1
}
Server response¶
{
code : 200,
details :
{ \
"page": 1, \
"updateBear": true, \
"assetId": "", \
"username": "Michael Merlange", \
"_organization": "5da8bdd0ca26fb0db035f451", \
"files": { \
"icon": { \
"filename": "03_pc_ani_blue.gif", \
"mimetype": "image/gif", \
"filesize": 3694, \
"url": "https://apicreator.argoflow.io/aura/media/607020ae9414053015f325dc/icon" \
} \
}, \
"_document": "60701ed89414053015f325db", \
"aura": { \
"api": "1.3.2", \
"actions": [ \
{ \
"data": "https://dev.indv.jp/sI0n/OOq3DKm2Bi", \
"type": "url" \
} \
], \
"background": "icon", \
"center_x": 47.70318021201413, \
"center_y": 46.874999999999986, \
"rect": [ \
97.17314487632508, \
68.75 \
], \
"center_z": 0, \
"name": "demo", \
"order": 1 \
}, \
"inserted": "2021-04-09T09:38:54.512Z", \
"updated": "2021-04-09T09:38:54.512Z", \
"id": "607020ae9414053015f325dc" \
}
}
New asset’s id is 607020ae9414053015f325dc
Javascript simple example¶
We can provide our customers with some html/javascript examples.
API versions¶
New version is to be released in May 2021¶
Current version of our API is V 1.3.2
Current APIs were mostly consumed by the ARGO editor.
We are about to offer a new set of APIs for external use :
- Renaming of concepts
- Better input and output
- Flexible requests : you will be able to request only a subset of data from a concept.
- Batch requests will be managed through APIs calls
NB : old APIs will continue to be maintained for at least a year, starting the day of the official new APIs release.
Link to test current API version¶
https://apicreator.ARGOflow.io/swagger/
Batch usage¶
Introduction¶
Batch mode is the recommended mode to generate Smartlinks outside of ARGOflow manager.
The main idea is that :
- a member, with no specific technical knowledge, can create templates through the ARGOflow manager
- Technical team can set up the batch to massively create customized copies of this template.
A template is a smartlink like any other but with some data that can be customized.
These data are identified by [[custom_data]] with custom_data the data that will need to be customized by the batch process.
Set up¶
Follow the README to install the server.
Create 2 files in the batch folder :
- param.json
- data.json
In your example, you can copy and rename *_genderF.json files.
Param.json¶
This file specifies general information about the batch :
- document_id : id of the smartlink you want to use as a template.
- https://argo.argoflow.io/demoforbatchgenderm.sl?sl=605daea5f453c80049ca6796, the document_id is 605daea5f453c80049ca6796
- dst_dir the subfolder in batch folder you want to write generated smartlinks in
- env : officialDev or officialProd.
- An environment is an object that mainly encompasses :
- url for API calls
- Url for event tracking
- An environment is an object that mainly encompasses :
- max_error : batch process will be stopped if the number of errors reached max_error. Otherwise it will go until the end. In any case, a report will be generated in dst_dir
Example :
{
"document_id": "605daea5f453c80049ca6796",
"dst_dir": "build",
"env": "officialProd",
"max_error": 0
}
Data.json¶
This file will list the needed customization for each Smartlink to be created.
It’s a json array with for each smartlink to be created :
- PDF_file : url of the underlying pdf. It needs to be accessible from where the smartlink will be eventually uploaded
- Data : an object with all the fields that need to be customized.
[
{
"PDF_file": "https://[...]/BasePDF_02.pdf",
"data": {
"url_video": "https://[...].mp4",
"tel": ""
}
},
[...]
]
NB : the batch mode is highly flexible and can be quickly customized to suit your own needs.
Run and follow¶
Once the server is started, and param.json/data.json are saved in the batch folder, just open your browser : [your server url]/generation/start
You will be given a link to get the job status at any time.
Final report will be saved in dst_folder as an html file.