Preparing add-ins for loading them to configurations

Content

Preparing add-ins for loading them to configurations

An add-in can be packed to a ZIP archive. This is mandatory if you want to use the add-in with the thin or web client or with the mobile platform.

The archive for the desktop platform must include add-ins for Windows  (x86, x86_64), GNU/Linux (x86, x86_64), extensions for Internet Explorer (x86, x86_64) and Mozilla Firefox (Windows x86, GNU/Linux x86, and x86_64).

The archive for the mobile platform must include add-ins for Windows RT (x86, ARM), Android (x86, ARM, and optional .apk file for Java code), and iOS (ARM and ARM64 combined in a single universal file). The iOS version must include both a static and a dynamic library.

The archive must also include the MANIFEST.XML file with the content description.

The archive for the mobile platform can also include the following optional files:

  • IOS_MANIFEST_EXTENSIONS.XML (for iOS). Describes the permissions to use additional frameworks.

  • ANDROID_MANIFEST_EXTENTIONS.XML (for Android). Describes the changes in AndroidManifest.xml.

  • WINDOWS_RT_MANIFEST_EXTENTIONS.XML (for Windows Runtime). Describes the changes in AppxManifest.xml.

  • WINDOWS_RT_PHONE_MANIFEST_EXTENTIONS.XML (for Windows Runtime Phone). Describes the changes in AppxManifest.xml.

In the desktop platform, add-in archives are loaded to configuration templates having "Add-in" or "Binary data" type.

In the mobile platform, add-in archives are loaded to configuration templates having "Add-in" type.

MANIFEST.XML file description

The following is an example manifest file:

<?xml version="1.0" encoding="UTF-8" ?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle" name="YourAddInName">
<component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
<component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
<component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="x86_64" client="Firefox" clientVersion="40.*" />
<component os="Windows" path="Addin_IEWindows_x86.cab" type="plugin" object="MyAddInIE.AddInServiceEx" arch="i386" client="MSIE" />
<component os="Windows" path="AddIn_IEWindows_x86_64.cab" type="plugin" object="MyAddInIE.AddInServiceEx" arch="x86_64" client="MSIE" />
<component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Chrome" />
<component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="i386" client="Chrome" />
<component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YourAddInName.1" arch="x86_64" client="Chrome" />
<component os="MacOS" path="AddIn_SafMacOS_x86.pkg" type="plugin" object="application/add-in-example-1" arch="i386" client="Safari" />
<component os="Windows" path="AddInNative.dll" type="native" arch="i386" />
<component os="Windows" path="AddInNative64.dll" type="native" arch="x86_64" />
<component os="Linux" path="AddInNative.so" type="native" arch="i386" />
<component os="Linux" path="AddInNative64.so" type="native" arch="x86_64" />
<component os="iOS" path="AddInNative_iOS.dylib" type="native" arch="Universal" buildType="developer" />
<component os="iOS" path="AddInNative_iOS.a" type="native" arch="Universal" buildType="release" />
<component os="Android" path="libAddInNative_Android_i386.so" type="native" arch="i386" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="i386" codeType="java" />
<component os="Android" path="libAddInNative_Android_ARM.so" type="native" arch="ARM" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="ARM" codeType="java" />
<component os="WindowsRuntimePhone" path="AddInNative_WinRT_Phone_ARM.dll" type="native" arch="ARM" />
<component os="WindowsRuntimePhone" path="AddInNative_WinRT_Phone_Win32.dll" type="native" arch="i386" />
<component os="WindowsRuntime" path="AddInNative_WinRT_x64.dll" type="native" arch="x86_64" />
<component os="WindowsRuntime" path="AddInNative_WinRT_Win32.dll" type="native" arch="i386" />
</bundle>

where:

  • name - unique add-in name (required for the mobile platform only), see 1C:Enterprise add-in naming rules

  • os - operating system, one of the following:

    • Windows

    • Linux

    • MacOS

    • WindowsRuntime

    • WindowsRuntimePhone

    • Android

    • iOS

  • path - file name in the archive
  • type - add-in type, one of the following:

    • plugin - browser extension

    • native - native component

    • com - COM component

    For the mobile platform, the only available type is native.
  • object - name of the object that will be created by the browser
  • arch - CPU architecture where the add-in will run, one of the following:

    • i386 - 32-bit 

    • x86_64 - 64-bit

    • ARM - 32-bit ARM

    • Universal - universal binary file for iOS containing executable code for ARM and ARM64

  • client - browser used by the web client, one of the following:

    • MSIE - Internet Explorer

    • Firefox - Mozilla Firefox

    • Chrome - Google Chrome

    • Safari - Safari

  • clientVersion - browser version (mandatory for Firefox)
  • buildType - target application type (iOS only), one of the following:

    • developer - application build intended for developers

    • release - application to be published

  • codeType - library programming language (Android only), one of the following:

    • c++ - library written in C++

    • java - library written using Java Native Interface

Correspondence between clientVersion values specified in the manifest file and Mozilla Firefox versions:

Manifest.xml Firefox
40.* 40 or later

When an add-in is changed (a new release or patch), add a new version number to the file name, for example: AddInNative_1_1.so. This rule does not apply to browser extensions. For extensions, change the object name.
Note that entries for Google Chrome and Mozilla Firefox refer to the same installer package.

1C:Enterprise add-in naming rules

Since a mobile application might use multiple add-ins created by different developers, it is important to employ the following add-in naming rules to eliminate possible naming conflicts.

An add-in name can contain Roman characters and numbers. Spaces are not allowed. Underscore (_) is allowed. The first character must be a letter or an underscore (_). Add-in names are case-sensitive.

If an add-in is developed in a company that has a website (for example, 1c.com), the add-in name must begin with the site name in reverse order, with periods replaced by underscores (for example, com_1c). Then add another underscore(_) and the add-in name.

If the site name does not comply with the add-in naming rules, try the following:

  • Replace prohibited characters, such as hyphens, with underscores.

  • If a name matches a reserved word, add an underscore to the end.

  • If a name starts with a number, add an underscore to the beginning.

Add-in limitations

Keep in mind that an add-in can be attached both in a window application (thick client or thin client) and in a console application (for example, on a 1C:Enterprise server or in a web client) that can lack the main window, other windows, event queue, timers that use the event queue, and the option to set an event hook (for example, to the keyboard). You have to ensure the availability of the environment required for correct add-in operation.

In mobile platform add-ins, do not call the following methods from the system thread because an application might stop responding after an attempt to open a modal window:

  • bool ADDIN_API Confirm (const WCHAR_T* queryText, tVariant* retval)

  • bool ADDIN_API Alert (const WCHAR_T* text)

For Windows Runtime and Windows Runtime Phone, the option to load dynamic libraries from web publications is not implemented.

IOS_MANIFEST_EXTENSIONS.XML file description

The builder uses the IOS_MANIFEST_EXTENSIONS.XML file for iOS only. The file grants the builder the right to use the frameworks required by the add-in. This file is optional. If it is not available, no changes are applied to the manifest file.

The following is an example manifest extension file:

<?xml version="1.0" encoding="UTF-8"?>

<root>
    <Additions>
        <framework name="System/Library/Frameworks/CoreMotion.framework"/>

        <framework name="usr/lib/libgll.dylib"/>

    </Additions>

</root>

The first line is a standard XML header. The second line contains the <root> tag.

You can only add data to the <Additions> tag.

The name="..." attributes of <framework> tags store framework names and paths.

ANDROID_MANIFEST_EXTENSIONS.XML file description

The builder uses the ANDROID_MANIFEST_EXTENSIONS.XML file for Android only. This file describes the changes to AndroidManifest.xml, such as rights that an add-in requires to access specific application components or functionalities. This file is optional. If it is not available, no changes are applied to AndroidManifest.xml.

The following is an example manifest extension file:

<?xml version="1.0" encoding="UTF-8"?>           
<root xmlns:android="http://schemas.android.com/apk/res/android">           
    <!--uses-permission android:name="android.permission.WAKE_LOCK"/-->           
    <uses-permission android:name="%application.package%.permission.MAPS_RECEIVE"/>           
    <target xpath="/manifest/application">           
        <uses-feature          
            android:name="android.hardware.sensor.accelerometer"
            android:required="true"/>          
    </target>           
</root>

The first line is a standard XML header. The second line contains the <root> tag with a fixed attribute, which has the same role as the <manifest> tag in AndroidManifest.xml.

The lines inside the <root> tag (except for <target> tags) are added to the <manifest> tag in AddroidManifest.xml without any changes or analysis.

The content of the <target> tags is added to AndroidManifest.xml part specified in the xpath="..." attribute.

You can have specific lines affect only specific packages by adding "%application.package%. ..." to those lines.

You can only add data to the following AndroidManifest.xml tags: <manifest> and </manifest/application>.

For the descriptions of uses-permission, uses-feature, and similar attributes, see the Android developer documentation.

We recommend that you do not add attributes that specify the maximum SDK version to uses-permission tags. This might cause conflicts when building applications with multiple add-ins.

WINDOWS_RT_MANIFEST_EXTENSIONS.XML and WINDOWS_RT_PHONE_MANIFEST_EXTENSIONS.XML file descriptions

The builder uses the WINDOWS_RT_MANIFEST_EXTENSIONS.XML and WINDOWS_RT_PHONE_MANIFEST_EXTENSIONS.XML files for Windows Runtime and Windows Runtime Phone, respectively. This file describes the changes to AppxManifest.xml, such as the rights that an add-in requires to access specific application components or functionalities. These file are optional. If they are not available, no changes are applied to the permission settings.

The following is an example manifest extension file:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <Additions>
        <target xpath="/Package/Capabilities/Capability[@Name='musicLibrary']"/>
        <target xpath="/Package/Capabilities/DeviceCapability[@Name='proximity']"/>
    </Additions>
</root>

The first line is a standard XML header. The second line contains the <root> tag.

You can only add data to the <Additions> tag.

The xpath="..." attribute of the <target> tag specifies the target of "Name='XXXXX'" parameters in the AppxManifest.xml file.

For the descriptions of <Capability> and <DeviceCapability> tags, see the Windows developer documentation.